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PREFACE 


MANUAL CBJECTIVES 


The RSX-11M/M-PLUS Guide to Program Development introduces the program 
development environment on the RSX-11M and RSX-11M-PLUS systems. It 
provides a synopsis of the information immediately useful in getting 
started in the program development process. The book also gives an 
overview of the software environment and some guidelines on program 
design. 


INTENDED AUDIENCE 


This book is intended for the person who is already familiar with the 
general, basic operations of an RSX-1iM/M-PLUS system: gaining access 
to the system, using the terminal and related devices, and requesting 
simple Executive services through the command interface. The greater 
part of the book addresses assembly language programming because that 
language is the one provided with all systems. Included is one 
chapter summarizing the program development procedures for a 
high-level language, PDP-11 FORTRAN IV. However, most of the topics 
covered for the assembly language programmer -- using a text editor, 
creating an executable image, using library facilities -- apply to 
programmers using any computer language. 


If you are not familiar with the general, basic operations of the 
system, you should first read the Introduction to RSX-l11M and 
RSX-11M-PLUS. This book describes how to access the system, use a 
terminal, and use the system command interface. 


STRUCTURE OF THIS DOCUMENT 


This guide is meant to be read aS you use the system. For this 
reason, the examples are presented in an order that you can follow at 
the terminal. Rather than demonstrate the complexity of the system, 
these examples are designed to demonstrate practical program 
development operations. 


This guide is also meant to be used with other manuals in your 
documentation set. Toward this end, a selection of further reading 
material is listed in the last section of each chapter. By using this 
guide, then, you can become increasingly familiar with other, more 
advanced manuals until you need not refer to this introductory text 
except as a refresher. 
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PREFACE 


The information in this book is organized into seven chapters, as 
follows: 


e Chapter 1, The Program Development Environment, introduces the 
software and hardware on which you develop programs. 


e Chapter 2, Creating MACRO-11 Source Files, describes how to 
create an assembly language source program using a skeleton 
file and text editor. 


e Chapter 3, Assembling and Correcting a Program Module, 
describes how to use the MACRO-11 Assembler to generate an 
object module. 


@ Chapter 4, Building and Testing a Task, describes how to use 
the Task Builder to link object modules to create a loadable 
task image. 


e Chapter 5, Using Debugging Aids, introduces debugging aids and 
discusses how to use them. - 


e Chapter 6, Creating and Using Program Libraries, describes how 
to create and maintain a library of macro source statements 
and a library of object module subroutines. 


e Chapter 7, FORTRAN IV Procedures, briefly introduces’ the 
FORTRAN IV program development process. ; 


ASSOCIATED DOCUMENTS 


As mentioned above, documents recommended for further reading are 
listed at the end of each chapter. In addition, the RSX-11M 
Information Directory and Index and the RSX-1iM-PLUS Information 
Directory and Index Tist and describe all the documents in the 
documentation sets for each system. 


CONVENTIONS USED IN THIS DOCUMENT 


Throughout this book, symbols and other notation conventions are used 
to represent keyboard characters, to convey textual information, and 
to otherwise ease the presentation of material. The symbols’ and 
conventions used are explained below. 


Convention Meaning 


OX) A 1- to 3-character symbol indicates that 
you press a key on the terminal; for 
example, @ indicates the RETURN key and 
indicates the LINE FEED key. 


GRLN) The symbol GN indicates that you must 
press the key labeled CTRL while you 
simultaneously press another key; for 
example, GRO indicates the CTRL and 0 


keys. In examples, this control key 
sequence is shown as “x; for example, “0 
indicates the result of typing CTRL) 
because that is how the system echoes many 
control key combinations. 
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Convention 


"print" and "type" 


MCR> 


DCL> 


red ink 


PREFACE 


Meaning 


The circumflex character, appearing with 
another character, represents the system 
response to receiving a control character 
(CTRL/n) . For example, when you type the 
CTRL/Z combination while running some system 
tasks, the system echoes “Z. (On some 
terminals, the circumflex is replaced by the 
up-arrow (ft) character.) 


As these words are used in the text, the 
system prints and the user types. 


This is the explicit prompt of the Monitor 
Console Routine (MCR), one of the command 
interfaces used on RSX-11M and RSX-11M-PLUS 
systems. 


This is the explicit prompt of the DIGITAL 
Command Language (DCL), one of the command 
interfaces used on RSX-11M and RSX-11M-PLUS 
systems. 


A right-angle bracket is the system command 
interface prompting character. Whenever 
control is returned to the user task 
terminal and you can type input, the prompt 
appears. 


RSX-11M and RSX-11M-PLUS systems can have 
one or more command line interpreters 
(CLIs). All systems include MCR and many 
systems include DCL. To determine which 
command interface your terminal has, type 
the CTRL/C combination and the explicit 
prompt (either MCR> or DCL>) will appear. 


Color-highlighted information in examples 
indicates information that you type. 
Information in examples not in the 
contrasting color constitutes computer 
output. 


Commas in commands’ separate parameters. 
They also indicate positional entries on a 
command line. 


A period in a file specification separates 
the file name and the file type. 


A semicolon in a file specification 


separates the file type and file version 
number. 
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CHAPTER 1 


THE PROGRAM DEVELOPMENT ENVIRONMENT 


This chapter introduces the software and hardware that you typically 
need to develop programs on an RSX-11M or RSX-11M-PLUS 
multiprogramming system. Its aim is to orient you to the environment 
in which you will be working. The remaining chapters in the guide 
further describe and illustrate how to use the tools and facilities 
introduced in the following sections. 


1.1 SOFTWARE TOOLS 


RSX-11M and RSX-11M-PLUS make software tools available as executable 
entities called system tasks. The system tasks include one or more 
editors, the MACRO-11 Assembler, the RSX-1I1M/M-PLUS Task Builder, 
several aids to debugging, and a number of utility tasks. Your system 
may also include one or more high-level language compilers or 
interpreters. These elements combined form the program development 
environment. In general, the system manager makes these tasks 
accessible to you by installing them on the system.1 


To invoke a task, you need not know where the task resides. The 
RSX-11M and RSX-11M-PLUS operating systems offer two command line 
interpreters for communicating with the system and invoking system 
services. These are the Monitor Console Routine (MCR) and the DIGITAL 
Command Language (DCL). MCR is included in all RSX-11M/M-PLUS 
systems, whereas DCL is optional, Each terminal is set to recognize 
either MCR or DCL upon logging in. 


1.1.1 Command Line Interpreters 


RSX-LIM/M-PLUS systems can have one or more command line interpreters 
(CLIs). All systems include MCR. Many systems include DCL, and some 
systems include user-written CLIs. Both MCR and DCL include commands 
to invoke most system tasks and utilities to set and display certain 
system characteristics. In general, MCR commands invoke tasks such as 
PIP, a utility used to manipulate files (for example, copying them). 
DCL commands specify actions directly, as in the COPY command or _ the 
TYPE command. 


MCR is the fundamental CLI for the RSX-11M/M-PLUS operating systems. 
From an MCR terminal, tasks installed with names in the form ...abe 


1. On systems with fewer resources, some tasks may not be permanently 
installed. Such systems may use the "flying install" feature, or 
require you to use some form of the RUN command to install system 
tasks temporarily. See your system manager for further information. 
This manual assumes that all tasks are installed. 
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can be invoked simply by typing the abc portion of the task name. 
Most system tasks and utilities are installed with names of that form. 
MCR also provides commands to set and display certain system and 
device characteristics. MCR provides the most direct interface with 
the operating system, either RSX-11M or RSX-11M-PLUS. 


DCL is an optional CLI included in most systems with heavy terminal 
use. Commands in DCL are English-like words and follow well-defined 
syntax rules. 


You are not required to use the full form of DCL commands, however. 
Usually, you need type only the command elements required to form a 
unique command. Most examples in this manual are in full format for 
clarity, but you should keep in mind that unless you are keeping a 
copy of your terminal activity for possible future reference, you can 
use much shorter forms than those in the examples. You will always be 
able to shorten any command or qualifier to four characters. Most 
commands and qualifiers can be entered with even fewer characters. 


DCL prompts you for all required command elements. Tf you do not 
understand a prompt, type in a question mark (?). DCL will print HELP 
text explaining the format and function of the command and then 
reprompt you for required input. 


DCL is actually a CLI task that translates DCL commands into MCR 
commands for execution by the system. The DCL SET DEBUG command 
displays the MCR translation for any DCL command on your terminal 
without executing the command. Depending on the kind of use you make 
of your system and the nature of your system, you may find it more 
convenient to use one CLI or the other, or both. All nonprivileged 
system functions are available directly from DCL, but some privileged 
functions are not. All program development facilities and all common 
utility functions are available from DCL. 


Your terminal is set to either MCR or DCL. You can determine which by 
typing a CTRL/C. The explicit prompt identifies the CLI. 


You can change from DCL to MCR, or vice versa, at any time. The DCL 
command SET TERM MCR switches vou from DCL to MCR The MCR comman 2 


aes yu 420 een CO riun, 41S of CUHUANa 
SET /DCL=TI: switches you from MCR to DCL. In addition, you can 
enter a single DCL command from an MCR terminal with the DCL command 
or enter a single MCR command from a DCL terminal with the MCR 
command. For example, the following commands have the same effect: 


DCL>MCR PIP TI:=filespec 


MCR>DCL TYPE filespec 


NOTE 


As shipped, DCL includes the SET DEBUG 
and MCR commands. These commands may be 
disabled at some installations. AS 
shipped, DCL also rejects any commands 
it does not recognize, but some 
installations may have enabled a feature 
that allows any command unrecognized by 
DCL to "fall through" to MCR for 
interpretation. See your system manager 
for more information on the limits of 
DCL at your installation. 


The RSX-~11M/M-PLUS Guide to Program Development concentrates on the 
actual program development process and not on DCL or MCR. However, 
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some of the program development facilities require different commands 
in DCL and MCR. In particular, the commands for the MACRO-11 
Assembler, the Librarian Utility Program, and the RSX-11M/M-PLUS Task 
Builder are different. While this will probably not interfere with 
your use of the system, it may be confusing at first. The programming 
demonstrations in this manual are documented first using DCL commands, 
then once again using MCR commands. This duplication enables you to 
see the differences between DCL and MCR. 


1.1.2 Text. Editors 


A text editor is the means by which you create a source code file. 
Most RSX-11M/M-PLUS systems include the Line Text Editor EDI and the 
DEC Standard Editor EDT. Both of these editors are interactive 
editing programs that enable you to enter ASCII text at a terminal and 
store the text in a disk file. They also let you access text in a 
disk file; examine, delete, and change text; and insert new text. 
The disk file is then used as input to other tasks in further steps of 
the program development process. 


EDI is introduced in this manual and further documented in the 
RSX~-11M/M-PLUS Utilities Manual. EDT is introduced in the 
Introduction to RSX-11M and RSX-11M-PLUS and further documented in the 


EDT Editor Manual. 


You can use EDI or EDT or some other editor found at your installation 
with the examples in this book. DCL users invoke an editor in the 
following manner: 


DCL>EDIT/EDI filespec 
DCL>EDIT/EDT filespec 
MCR users invoke an editor in the following manner: 
MCR>EDI filespec 
MCR>EDT filespec 


In both DCL and MCR, the EDT command line can include other command 
elements to invoke special features of EDT. 


EDI may be the only editor available on smaller systems. 


EDI is a single-pass, line-oriented editor. In its typical mode of 
operation, called block mode, it reads from a disk file a block of 
text -- as much text as will fit in its text buffer. You perform 
editing operations on text in the EDI buffer. After editing text in 
the buffer, you request the editor to renew the buffer with the next 
block of text. To change text in a previously edited buffer, you must 
close the current editing session, open the file again by reinvoking 
EDI, and read from the beginning of the file to the block of text. 


Editing functions are on a line-by-line basis. New text is inserted 
into the buffer one line at a time. Current text in the buffer is 
changed by your locating the line or lines on which EDI must make the 
change. 


To preserve currently existing text, EDI performs all processing on a 
temporary copy of the file being edited. As you renew text in the 
buffer, EDI writes the edited text to a temporary file. This action 
has two advantages and one drawback. First, the current version of 
your text file is always left intact. Second, when you exit from the 
editing session, you have the option of storing the edited file ina 
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new version of the old file or of creating an entirely new file (that 
is, one with a different name and version number). The drawback of 
the temporary file is that, in the event of a System crash, edits you 
are making are lost. After a crash, the new version of the file has a 
zero length because EDI did not have time to preserve the edits from 
the temporary file. 


1.1.3 Assembly Language 


RSX-11M and RSX-11M-PLUS systems support many programming languages. 
However, the one language distributed on all systems is the PDP-11 
assembly language, MACRO-11. MAC is the task that assembles MACRO-11 
language files. It accepts a disk source input file in ASCII format 
and can create a relocatable object module and a listing file of the 
Source language. The object module contains all the object records 
and relocation information needed to link with other object modules. 
All symbol definition done by the assembler has a base address of 
zero, The allocation of virtual addresses and relocation is left for 
the task-building process. 


DCL users invoke MAC with the MACRO command. MCR users invoke MAC 
with the MAC command. 


Source input to MACRO-11 consists of free-format statements, each line 
of input containing a single statement. Input statements are either 
PDP-11 instructions, MACRO-11 Assembler directives, macro calls, or 
direct assignments. Statements can contain labels to allow control to 
change locally (within the module) or to enable control to be passed 
between modules (globally). 


Source input usually contains user-defined symbols, which are either 
local or global. A local symbol is defined in the current source file 
and is referenced only within the current file. A gliobal symbol is 
defined in one source file but can be referenced in one or more other 
source files. 


The assembler allows you to use both local and global symbols as 
labels for statements. When a global symbol appears as a label, the 
related statement is referred to as an entry point (that is, a point 
at which other modules can transfer control to the current object 
module). You can use local symbols as statement labels to define 
points to which control transfers within an object module. 


The assembler evaluates all local symbol definitions in a source file. 
Any symbols remaining undefined are classified as global. Thus, after 
an assembly, all local symbols are assigned relative locations, but 
the module may contain references for which definitions must be 
supplied. The resolution of these references is left for the 
task-building process. 


Assembler directives in a source file allow you to perform operations 
such as the following: 


e@ Program sectioning 
e Listing control 
@ Conditional assembly 
e Data storage 
Program sectioning allows code or data within an object module to be 


overlaid by, or concatenated with, code or data in other object 
modules or in noncontiguous locations within the same module. Program 
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sectioning is especially useful where convenient physical ordering 
differs from logical reference ordering (for example, in 
table-generating macro statements). Listing control directives enable 
documentation features such as listing-heading lines, listing-page 
formatting, and table of contents generation. Conditional assembly 
directives allow optional omission or inclusion of lines of code or 
user-defined symbols. Using data storage directives, you can control 
the size and contents of data areas. 


Special statements called macro directives allow you to reference a 
predefined symbol that causes the assembler to expand a single line 
source statement into multiple lines of code or data and insert the 
assembled result in the object module. Such macro symbols are 
typically used for recurring coding sequences. The insertion of the 
code sequence occurs at each point you refer to the macro symbol. 
Definitions for such macro symbols can occur in the source file itself 
or can reside in a macro library. Generally, you place infrequently 
used macro definitions in the source file that invokes them, and store 
frequently used macro definitions in a macro library. The Executive 
and file-processing services are made available to the program through 
macro symbols that are defined in a DIGITAL-supplied macro library. 


MACRO-11 is a 2-pass assembler. During the first pass, the assembler 
groups all symbols as either local or global, performs statement 
generation, locates all macro symbols, and, if necessary, reads the 
macro definitions from libraries. At the end of pass 1, the assembler 
must have processed all local references (such as all undefined global 
symbols) that are to be resolved by the Task Builder. 


During the second pass, the assembler actually generates the object 
module and listing files, flagging with an error code in the listing 
file those source statements containing errors. If you requested a 
cross-reference listing of symbols, the assembler also generates a 
request for the Cross-Reference Processor (CRF) to create the proper 
information. (CRF is introduced in Section 1.1.6 in this chapter.) 


The MACRO-11 listing file provides both documentation for the module 
and a tool for debugging the code. As a reference aid, the assembler 
generates and includes line numbers in the listing for each statement 
in the source file. It also maintains a current location counter for 
each program section defined in the source file. In addition, the 
listing includes a symbol table showing symbols, their attributes, and 
their values if known at assembly time. 


The location counter value given in the listing file is vital in 
debugging because it provides the offsets into the module for each 
program section. An offset, combined with the base load address for a 
program section (from the Task Builder map), allows you to access 
locations in the memory-resident task image during debugging. 


1.1.4 Task Creation 


The Task Builder (TKB) on RSX-11M and RSX-11M-PLUS systems is a 
multiple-purpose tool. It allows you to create a loadable entity 
(called a task image), define and structure a shared area of memory 
(called a resident common), and arrange shareable routines to reside 
in memory (called resident libraries). TKB has many complex aspects 
but this guide introduces only its most frequent usage: building a 
task image. 


DCL users invoke TKB with the LINK command. MCR users invoke the TKB 
with the TKB command. 


To build a task image, TKB accepts, as basic input, the output of a 
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language processor: an object module or multiple object modules. TKB 
can optionally generate a file of executable code (the task image), a 
file of memory allocation information (a map), and a special file of 
symbol definitions used in constructing the task (the symbol 
definition file). The task image, residing on disk, is in a format 
Suitable to be loaded into memory and executed. If you generate a 
cross-reference listing, the listing itself contains only global 
symbols and is appended to the map file. 


In creating a task image, TKB's primary functions are linking, address 
binding, and building system data structures. Linking involves 
resolving global references in all object modules and resolving 
Program section references among all object modules. Address binding 
is assigning virtual address space within the task. Building system 
data structures involves creating elements that the system requires to 
load the task image into memory and to execute the task. To resolve 
global symbols that are not defined in any of the input object 
modules, TKB searches any object libraries you specify and, as a 
default condition, searches the system object library. 


Because the PDP-11 processor can address only 32K words (the address 
limit of 16 bits) at any one time, a task cannot reference more than 
32K words at a time. However, if you use certain advanced programming 
techniques, TKB allows a task to access more code or data than can fit 
within the address limits. Techniques to overcome the addressing 
limits include the following: 


e Ove of a task with either disk-resident or 


e Mapping to different regions of memory outside the physical 
limits of the current task space 


Because these are advanced techniques, they are not shown in the 
examples in this guide. For more information on them, refer to the 
RSK-1iIM/M-PLUS Task Builder Manual. 


The memory allocation information, or map, produced by TKB shows you 
how program sections are arranged in task Memory (their starting 
virtual addresses and extents on mapped systems and physical addresses 
and extents on unmapped systems), what contributions are in a program 
Section, any undefined symbols, and the optional cross-reference 
listing of global symbols. You can use the starting virtual 
addresses, combined with the current location counter values (provided 
by the assembler), as offsets to access locations within the 
memory~resident task during debugging. 


1.1.5 Debugging Aids 


This section introduces the debugging aids described in this guide and 
provided with RSX-11M and RSX-11M-PLUS systems to assist in 
identifying faulty code. 


1.1.5.1 On-Line Debugging Tool ~- The On-Line Debugging Tool (ODT) 
allows interactive control of task execution. You specify to TKB that 
you want a debugging aid included in a task. TKB inserts into the 
task the module LB:[{1,1]ODT.OBJ. 


When you run a task that includes ODT, execution begins at the ODT 
transfer address rather than at the task starting address. Therefore, 
ODT gains control and allows you to type special commands’ that 
establish base addresses and that set breakpoint locations within the 
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task. After you tell ODT to begin task execution, ODT saves the 
instructions at breakpoint locations you specified and replaces them 
with PDP-11 breakpoint (BPT) instructions. Upon encountering a BPT 
instruction in the task, the Executive passes control to ODT at its 
breakpoint routine. ODT saves task registers in special locations, 
restores instructions to the breakpoin locations, and transfers 
control to the user task terminal. By typing ODT commands, you can 
examine and alter any instructions or data within task memory. 


ODT also enables the BPT synchronous system trap (SST) entry point in 
the task. If a task generates an SST error, ODT gains control at its 
SST entry point, prints a notice at the user terminal, and passes 
control to the terminal. You can use the ODT commands to discover the 
cause of the error, correct it, and perhaps continue executing the 
task. 


To successfully modify instructions, you must have a thorough 
understanding of the PDP-11 instruction set. If you are programming 
in a high-level language, you should avoid interactive debugging 
whenever possible. 


1.1.5.2 Postmortem Dump - Postmortem Dump (PMD) is an installed task 
that is directed by the Executive to extract run-time related data 
about a terminated task, format it, and request a printed listing.1 
Normally, when a task generates a synchronous system trap (SST), such 
as that caused by an improper reference to an odd address or a 
reference to a nonexistent memory location, the Executive tries to 
transfer control to an SST entry point defined by the task. If the 
task does not have an SST routine defined for the particular type of 
trap, the Executive aborts the task. 


To terminate the task, the Executive performs an abort operation and 
notifies the Task Termination Notification program (TKTN). TKTN 
displays, on the user terminal, the reason for the termination and the 
contents of the task registers.2 Without PMD, you can acquire no 
further information about the task.3 


By enabling Postmortem Dumps for a task that itself does not handle 
synchronous system traps, you tell the Executive to supply more data 
at abnormal task termination. That is, the Executive follows the 
abort procedure and, in addition, creates a request for PMD to create 
the dump. PMD examines system and task structures to preserve status 
and run-time data, reads the task image from memory, and writes it to 
disk in a readable format. PMD then queues a request to print the 
file containing the dump data, after which the Executive completes the 
task abort procedure. 


1.1.5.3 Snapshot Dump - The snapshot dump (S$SNAP), also using PMD, 
generates an edited dump of a running task. Because the snapshot dump 


1. PMD requires that the Executive option for abnormal task 
termination and device-not-ready messages be selected at system 
generation time. 


2. The TKTN task must be installed on the system to display the 
messages, 


3. Commands exist that allow you to fix a task in memory and 


physically examine the contents of the task image. However, this is a 
complicated procedure and beyond the scope of this book. 
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requires you to insert special code (for example, the $SNAP macro 
call) in a task, it is more difficult to use than PMD. However, by 
inserting the snapshot dump code in the task, you can choose the 
location at which the dump is created and select the extent and format 
of the dump. In addition, you can generate the dump from more than 
one location and, therefore, as many times as needed during task 
execution. 


It is often useful to include debugging facilities such as S$SNAP in 
your task based on defining a conditional variable. To include the 
facility while you are debugging, simply define the variable. You can 
then omit the facility by reassembling the code with the conditional 
‘variable undefined. 


1.1.6 General Utilities 


This section introduces the general-purpose utility programs that are 
mentioned in this guide. 


1.1.6.1 Cross-Reference Processor - The Cross-Reference Processor 
(CRF) is an installed task that receives requests from MACRO-11 and 
TKB to generate cross-reference listings of symbols. CRF generates a 
specially formatted file containing the cross-reference data and 
appends that file to the assembler listing or the task map file. 
Therefore, if you request a cross-reference listing of symbols, it 
always appears at the end of a listing or map file. 


A request for the services of the Cross-Reference Processor is 
included in your command line to the MACRO-11 Assembler and TKB. From 
DCL, use the /CROSS REFERENCE qualifier to the MACRO and LINK 
commands. From MCR, use the /CR switch on the proper file 
specification in the MAC and TKB command lines. 


1.1.6.2 Peripheral Interchange Program - The Peripheral Interchange 
Program (PIP) is the standard DIGITAL program for performing file and 
device-related functions: transferring files from one medium or User 
File Directory (UFD) to another, obtaining directory listings, 
renaming files, deleting files, and changing file protection codes. 
PIP handles all Files-11 file-structured devices and is used for 
almost all file operations. The noteworthy exception to PIP 
capabilities is certain PDP-11 Record Management Services (RMS-11) 
file operations, for which DIGITAL supplies special RMS-11l utilities. 


MCR users access PIP services through various PIP commands. DCL 
includes the DIRECTORY, DELETE, PURGE, COPY, RENAME, TYPE, APPEND, and 
SET PROTECTION commands, which give you transparent access to PIP 
services, 


1.1.6.3 Queuing and Spooling - RSX-11M and RSX-11M-PLUS systems 
differ in the manner in which each provides queuing and spooling 
facilities, but both systems generally offer the same user functions. 
Almost all program development tasks automatically generate requests 
to the proper queuing tasks to print an ASCII output file on the 
system's default printer. If your installation has the proper tasks 
installed, the spooling task dequeues such requests and prints the 
requested output file on the proper device. You should consult the 
system manager at your installation for the exact details. 
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1.1.6.4 Librarian Operations - The Librarian Utility Program (LBR) 
can create and maintain specially formatted library files on disk; 
one for macro call definitions and one for object module subroutines.1l 
The MACRO-1l1 Assembler and TKB can access these library files and 
extract the proper code from them. Libraries are convenient to use 
because they encourage sharing of code, provide faster access to 
multiple modules (only one file need be opened and closed), occupy 
less space than the equivalent number of separate modules, and impose 
a coding standard. The library files you create using LBR are in the 
same format as those that DIGITAL supplies with the operating system. 


DCL includes a series of LIBRARY commands that give you access to LBR 
services. MCR users access LBR services through various LBR commands. 


1.2 DIGITAL-SUPPLIED SYSTEM SOFTWARE 


DIGITAL supplies system software in two standard library formats: 
macro call definitions and object module subroutines. You use macro 
libraries as input to the assembler and object libraries as input to 
TKB. The following two subsections describe these system libraries. 


1.2.1 System Directives - Macro Libraries 


DIGITAL makes available system directives and system-related features 
through calls; definitions for these calls reside in macro libraries. 
The libraries are stored in a predefined file area known as a User 
Pile Directory or UFD. The UFD is [1,1] on the system library device 
(referenced explicitly by the device-independent designation LB:). 
Table 1-1 summarizes the macro libraries that DIGITAL supplies. 


Table 1-1 
DIGITAL-Supplied Macro Libraries 


File Name and Type Description of Contents 


RSXMAC.SML System Macro Library. Contains the macro 
definitions for all RSX-11M and RSX-11M-PLUS 
system directives and File Control Service 
(FCS) file-processing calls. Default library 
for the assembler. 


EXEMC.MLB Executive Macro Library. Contains the symbol 
and offset definitions for the Executive data 
structures. 

RMSMAC.MLB PDP-11 Record Management Services (RMS-11) 
Library. Contains the definitions for RMS-11 
calls for sequential and relative file I/0. 
If your system has the optional RMS-11K 
software, this library will also contain 
calls for indexed file operations. 


1. The Librarian can also create a universal library file to contain 
any of one file type you prefer. 
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To use these libraries, you should follow the specific procedures 
described in the system documentation. Typically, you supply in the 
source code the appropriate names of the modules as Parameters of a 
«MCALL MACRO-11 directive. This action tells the assembler to 
generate an entry for that call in its macro symbol table and to 
search the appropriate library for the definition of the macro symbol. 


In translating source code, the assembler first checks for macro 
symbols. When the assembler finds an operator on a source line, it 
searches its macro symbol table to see whether the operator is a macro 
symbol. An operator is any PDP-11 operation code, MACRO-11 Assembler 
directive, or macro symbol. If the operator is a macro symbol, the 
assembler applies the local definition for the macro symbol or 
extracts the definition from a library you specified or from the 
system library. By searching the user-supplied library first, the 
assembler allows you to tailor the definitions of system macro calls 
or PDP-1l instructions. MACRO-11 assembles the macro definition with 
any accompanying parameters and includes the assembled code in the 
object module. As a result, the proper code is included from a 
library. 


Through the use of the system macro library, you are provided with the 
code that enables a task to issue system directives and to obtain the 
File Control Services (FCS). These services enable a task to obtain 
run-time and system information, perform input/output functions, 
communicate with other tasks, manipulate logical and virtual address 


and RSX-11M-PLUS features are made available to a task Ehsough “maers 
calls to the system macro library. For the system macro library 
RSXMAC, you need not designate the library name to the assembler. As 
a default condition, the assembler automatically searches the system 


macro library. 


Through the use of the Executive macro library EXEMC.MLB, you are 
provided with code to allow software te refer to offsets within the 
Executive and system definitions of the Executive data structures. 
This library is provided for assembling privileged tasks and for 
incorporating specially written device drivers into the system. (This 
topic is covered fully in the RSX-11M-PLUS Guide to Writing an 1/0 
Driver, the RSX-11M Guide to Writing an I/0 Driver, and the 
RSX-11M/M-PLUS Task Builder Manual, and is not mentioned further in 
this guide.) 


The Record Management Services library RMSMAC.MLB is provided to 
support file and record access to RMS-1l data. RMS-11 is an 
upwards-compatible extension of FCS and offers more functions such as 
indexed sequential (keyed) access to data. You include the RMS-l1l 
macro symbols in the source code and supply to the assembler the name 
of the RMS-11 library to use. The assembler extracts the definitions 
from the library and includes the RMS-11 code in the object module, 


1.2.2 System Subroutines - Object Libraries 


On RSX-11M and RSX-11M-PLUS systems, system object libraries provide 
general utility functions and special-purpose Executive features. 
These libraries, like the macro libraries, reside in UFD {1,1] on the 
system library device (LB:). Table 1-2 lists and describes the object 
libraries that DIGITAL supplies. 
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Table 1-2 
DIGITAL-Supplied Object Libraries 


File Name and Type Description of Contents 


SYSLIB.OLB System Library. Gontains register handling, 
arithmetic, data conversion, output 
formatting, File Control Services (FCS), and 
FCS command line processing subroutines. 
Optionally contains a set of real-time data 
acquisition routines. Default library for 
TKB. 


dynamic memory, core allocation, virtual 

Memory, and page management subroutines. 
EXELIB.OLB Executive Library. Contains the definitions 
of the Executive symbols. 
ANSLIB.OLB ANSI Magnetic Tape Library. On RSX-11M 
systems only, an alternate version of 
SYSLIB. Contains ANSI magnetic tape label 
handling routines and FCS big buffering 
support. (On RSX-11M-PLUS systems and 
systems with limited disk space, these 
routines are in SYSLIB.) 
RMSLIB.OLB Record Management Services Library. 
Contains the routines for sequential and 
relative (RMS-11) and, optionally, indexed 
(RMS-11K) I/0. 


| 
VMLIB.OLB virtual Memory Management Library. Contains 


FOROTS.OLB FORTRAN IV and FORTRAN IV-PLUS Library 
F4POTS.OLB (optional). The Object Time System (OTS) 
and other routines for the PDP-11 FORTRAN IV 
language processors. 


You typically include system object routines in a task by specifying 
the routine name as the operand of a CALL macro or Jump To Subroutine 
(JSR) instruction in the source code. The language processor, at the 
point of the reference, generates the instructions to transfer control 
to the external subroutine. The name of the subroutine is left as an 
externally-defined global symbol for TKB to resolve. 


To ensure that subroutines are placed in the task image, TKB, as a 
default operation, searches the library SYSLIB.OLB for routine names 
that remain undefined after the search of any user-specified 
libraries. TKB attempts to match the undefined global reference (the 
subroutine name in a module) with an entry point name in the SYSLIB 
library. When it finds a match, TKB extracts a copy of the module 
defining the symbol from SYSLIB and inserts the subroutine in the task 
image. Any further references to that symbol in the task are defined 
by the subroutine, and TKB need not add any code to resolve further 
references. 


If a module references routines that are in an object library other 
than SYSLIB.OLB, you must specify that library when you build the 
task. TKB performs the same search operations on user-supplied 
libraries as it does on the default search of SYSLIB. MTKB also 
searches any user-specified libraries in the order in which you 
specify them before it searches the system library. 
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1.3 HARDWARE FOR PROGRAM DEVELOPMENT 


Basically, you need three types of devices for program development: 
disks, terminals, and printers. This section briefly introduces these 
devices and tells where you can find further information. In general, 
each hardware unit on the system is delivered with relevant hardware 
documentation that provides programming information in addition to 
operational instructions. Your installation should have a library of 
such hardware documentation. If you are not writing any specially 
tailored code for these devices, the system software handles them 
transparently through such mechanisms as the print spooler and PIP. 


1.3.1 Disks 


Disks are the main storage media on RSX-11M and RSX-11M-PLUS systems. 
Disk drives are either public (that is, accessible to all users) or 
private (that is, accessible to a restricted set of users). Almost 
all utility programs work with disks as their default device. You can 
share public disk resources to create source program files and, as 
needed, allocate your own private drive to store reserved copies of 
source and documentation files. 


1.3.2 Terminals 


Terminals are the means by which you communicate with the system. 
DIGITAL terminals handle 7-bit ASCII characters and system software 
usually ignores any eighth, or parity, bit. You perform input to the 
system through a typewriter-like keyboard; the system returns output 
to you either on a screen at a video-display terminal or on paper at a 
hard-copy terminal. Video-display terminals are more convenient 
because they typically operate at faster rates than hard-copy devices. 
Hard-copy terminals, however, have the advantage of providing a record 
of what transpired during a session on the system. 


Terminals are connected to the computer through either a direct line 
or a modem unit over a dial-up telephone line. If you are not 
familiar with using a terminal, you should read the Introduction to 
RSX-11M and RSX-11M-PLUS and_ the RSX-11M/M-PLUS Command Language 
Manual, These manuals explain how to access the system and basic 
system functions using DCL. The RSX-11M/M-PLUS MCR Operations Manual 
explains how to access the system and  baSic system functions using 
MCR. 


1.3.3 Printers 


Printers provide hard-copy output of data. On larger systems, you 
communicate with the printer through the Queue Manager subsystem. 
(See the RSX-1L1M/M-PLUS Batch and Queue Operations Manual for more 
information on the Queue Manager.) MCR Provides a PRI command and DCL 
a PRINT command on systems with the Queue Manager. On smaller 
Systems, you may have to specify explicitly that output is to go to a 
line printer. All systems have a terminal or other output device 
serving as a line printer. All listings from the MACRO-11 Assembler 
or TKB are queued to the system line printer. 
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1.4 THE PROGRAM DEVELOPMENT PROCESS - OVERVIEW 
Figure 1-1 illustrates the steps in the program development process. 


The following paragraphs briefly describe these steps, which are 
treated in greater detail in Chapters 2 through 7. 


START 
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Figure 1-1 The Program Development Process 
The steps normally taken to prepare a program to run on the system are 
as follows: 
1. Create a source program in a file on disk. 


2. Submit the source file to a language processor (assembler or 
compiler) to produce an object module. 


3. Submit the file (or files) containing the object or modules 
to TKB to create a file containing a loadable task image. 


4, Request the Executive to execute the task. 


You use a text editor to create the source file. For MACRO-11 
programmers, this guide suggests a skeleton format for source files 
and shows how to replicate and modify the skeleton file. The skeleton 
file becomes a common base from which you create each new source file. 
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A language processor creates the file of relocatable object code. For 
assembly language processing, MACRO-11 also accesses the system macro 
library to include code for system directives in the object file. For 
compilers, system directives are invoked by calls to subroutines in 
the system object library SYSLIB,. 


TKB creates the file of loadable code, assuming certain default 
conditions about the run-time environment and building these 
characteristics into the task. TKB also accesses system and 
user-specified libraries to resolve references in the task. 

Once you have a task image, you request the Executive to run the 
program. If any errors are encountered, you must edit the source 


file, reassemble or recompile, build a new task image file, and try 
again. 


1.5 GUIDE TO FURTHER READING 
The sections or chapters in the following documents contain additional 
information on the subjects described in this chapter. 
Document 

Introduction to RSX-11M and RSX-11M-PLUS 
RSX-11M/M-PLUS Command Language Manual 

Chapter 1, Introduction 

Chapter 3, Terminal Operations 

Chapter 4, Handling Files 

Chapter 6, Program Development 
RSX-11M/M-PLUS MCR Operations Manual 


Chapter 1, Introduction to MCR 
Chapter 2, System Conventions 


RSX-11M/M-PLUS Utilities Manual 
Chapter 1, Introduction 

EDT Editor Manual 
Chapter 1, Introduction to EDT 


RMS-11 User's Guide 
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CREATING MACRO-11 SOURCE FILES 


Your first step in program development is to create a file that 
contains MACRO-11 source statements. One way to do this is to create 
a skeleton source file that you can use as a framework for all your 
source programs. This chapter describes a source file format that you 
can use aS a guideline to create your own skeleton file, presents some 
MACRO-11 statements to include in the file, and explains some 
elementary editing commands that you can use to create and modify 
source files. 


DIGITAL has established a coding standard to enhance the readability 
and maintainability of its MACRO-11 source programs. That standard is 
outlined in an appendix of the PDP-11 MACRO-11 Language Reference 
Manual, the reference for which is given in the list of further 
reading at the end of this chapter. 


2.1 MACRO-11 SKELETON SOURCE FILE FORMAT 


This section presents the skeleton and source statement formats and 
discusses each of the elements in the _ skeleton. Figure 2-1 
illustrates the basic elements of the skeleton: a preface, 
definitions, functional descriptions, and the code itself. 


The source file preface, or preamble, should be on the first page. 
The preface essentially describes the code, states its ownership, 
identifies the author, defines the changes to the code, and gives a 
brief description of the module's function. 


After the preface of the module comes the detail of the code. 
Declarations, such as local symbol, macro, and data definitions, 
appearing toward the front of the code, make reading the code easier. 
Preceding the routines in the module you should place detailed 
descriptions of what the routines do, and define what is required for 
input to the routines, what the routines produce, and what effects 
result from execution. 


Each statement li 
format, as shown 


e a source file should follow a consistent 


ne in 
in Figure 2-2. 
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Title 
Identification 


Statement of Ownership 


Change History 


: Module Preface 
Authorship on first page 


Module Function 
(General) 


| Local Symbol Definitions | 


————— cs | 


Local Macro Definitions 


Local Data Blocks 


Module Function 
(Detailed) 
Inputs, Outputs, 
and 
Side Effects 


Module Code 


Figure 2-1 MACRO-11 Source File Format 
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| | | 


Tab Position 0 Tab Position 1 Tab Position 2 Tab Position 4 
Column 1 Column 9 Column 17 Column 33 
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Figure 2-2 MACRO-11 Source Statement Format 


Although the assembler allows free formatting of statements, you 
should follow the recommended format because it is easy to follow and 
creates readable, consistent code. 


In the source statement format shown in Figure 2-2, the label is any 
user-defined symbol that identifies a reference location in the code. 
An operator is any PDP-11 operation code, MACRO-11 Assembler 
directive, or macro symbol. An operand is any argument(s) or 
parameter(s) of an operator. Comments consist of information you 
provide to describe what effect you desire from the execution of the 
instruction. Comments do not affect program execution; the assembler 
merely transfers them to the listing file produced during the 
assembly. 


Comments, accompanied by selected MACRO-11 Assembler directives, 
constitute the source file skeleton. This skeleton provides the 
structure on which you build the source file. Directives in the 
source file skeleton identify the code and control the format of the 
listing. Example 2-1 shows a sample skeleton. 


Sections 2.1.1 through 2.1.12 describe the parts of the source file 
skeleton in detail. 


2.1.1 .TITLE Directive 


The .TITLE directive allows you to name the module. The assembler 
takes the first six nonblank characters, up to the first blank or 
horizontal tab character, as the module name. Following the name in 
the .TITLE directive, you can use up to 24 characters to describe 
generally the function of the module. The name and the description 
appear as the first entry in the header line of each page in the 
assembly listing. For example, consider’ the following . TITLE 
directive: 


»TITLE SKELTN SOURCE FILE SKELETON 


The assembler takes the characters SKELTN as the module name. The 
remaining characters up to the 30th character are taken as the 
description. Any remaining characters after the 30th character would 
be discarded. 


The assembler does not relate the name you specify in the .TITLE 
directive to the name you specify for the source or object files. To 
minimize confusion, however, it is helpful to apply the name specified 
in the .TITLE directive to the source file. (Note that the sample 
code and commands shown in this guide use different names to help you 
distinguish their usages.) 
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Example 2-1 Sample Source File Skeleton 


«TITLE SKELTN SOURCE FILE SKELETON 
+IDENT /01/ 


AUTHOR: Z 


cap ar ae eP 


CHANGES? 


“a a> ee 


MODULE FUNCTION? 


ep er > 


+» PAGE * BREAK PAGE FOR PREFACE 
*SBTTL SYMBOL+ MACROs DATA DEFINITIONS 

«LIST TT 

+NLIST BEX sSUPFRESS BIN EXTENSION 
»MCALL EXITSS sEXEC’S EXIT MACRO 


LOCAL SYMBOL DEFINITIONS: 


<p ap en 


LOCAL MACROS? 


o> 4d oP 


LOCAL DATA BLOCKS: 


> a> ar 


*PSECT DATA:D:RW 


FUNCTION DETAILS? 


INPUTS 
OUTPUTS: 


SIDE EFFECTS: 


Oh 8b es Oe ee OP ee ee EE ae 


START COBE HERE 


od 


+PAGE 
+SETTL 
+PSECT 
START? 
END: EXIT$S sEXIT CLEANLY TO EXEC 
» END sTELL ASSEMBLER END OF CODE 
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Moreover, the name the assembler extracts from the .TITLE directive is 
important in subsequent steps of program development. The Task 
Builder (TKB) lists this name in its memory allocation synopsis’ to 
show which object modules made contributions to each program section 
in the task image. In addition, if the object module is inserted in 
an object library, the Librarian Utility Program (LBR} keeps this nam 
in the directory of the library to refer to the object module. 


2.1.2 .IDENT Directive 


The .IDENT directive records the version of the module. You can 
establish your own version identification conventions. The 
identification follows the module into the task image and is displayed 
in the map. Knowing whether the correct version of the module was 
linked into the task image helps in the debugging and maintenance 
process. 


2.1.3 Author Line 


The author line identifies the originator of the code. 


2.1.4 Changes Section 


This section of the source file describes any modifications that have 
been made to the module. You can develop a convention whereby the 
author's initials and a number can tag a change. The author of the 
change can identify the change in this section and flag each line of 
code with an additional comment, such as the following: 


TOM JONES 8-AUG-81 7TICOL 
ADD STATE TAX TO TOTAL 


we 


Then, in the code a changed or added line can be flagged with the 
notation TJOO1. 


ADD A,B ;TOTAL WITH TAX ;TJOO1 


This procedure helps the author recall what changes were made to _ the 
module and assists others in determining the extent of changes.1 


2.1.5 Module Function 


In the module function part of the source file, you can describe the 
general processing operations that the code performs. This 
description can include how the module relates to the system or 
specific application, that is, what type of processing precedes and 
follows the execution of this module. 


1. A utility called the Source Language Input Program (SLP) is 
supplied with the system and can be used for source file maintenance. 
SLP provides the means to update lines in an existing source file and 
to apply an audit trail to identify lines deleted, replaced, and 
added. MCR users access SLP through various SLP commands. DCL users 

access SLP through the EDIT/SLP command. 
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2.1.6 Some Useful Directives 


Between the module function description and the local symbol 
definitions is a convenient place to insert some general-purpose 
directives. The following subsections describe these directives. 


2.1.6.1 .PAGE Directive - The .PAGE directive causes a page break in 
the assembly listing. It appears as shown in Figure 2-3 to keep the 
preamble alone on the first page of the listing (after the table of 
contents). You can use the .PAGE directive throughout the module to 
generate page breaks for different subroutines. 


2.1.6.2 .SBTTL Directive - The .SBTTL directive creates an entry for 
the assembly listing table of contents printed at the front of the 
listing. A table of contents is helpful in summarizing the 
subroutines in a large module. Therefore, the text you supply with 
the directive ought to describe what the related subroutine does. In 
addition to appearing in the table of contents, the text appears on 
the second line of the heading at the top of each listing page. If 
your modules typically contain only a small number of subroutines, you 
probably will not find the table of contents feature very useful. 


2.1.6.3 LIST TTM Directive - The .LIST TT directive creates a 
listing formatted more conveniently for ouput on a terminal. (Section 
3.4 of this guide shows how to display a listing at a terminal.) The 
directive can be included during the early stages of program 
development and removed from the stabilized code. 


2.1.6.4 .NLIST BEX Directive - The .NLIST BEX directive suppresses 
the binary extension of statements beyond what can fit on one source 
statement line. Using this directive saves much excess printing in 
the assembly listing. For example, only the binary value of the first 
three characters of an ASCII string would appear in the listing. The 
directive simply makes the listing more readable and saves paper. 


2.1.6.5 .MCALL Directive - The .MCALL directive is the means by which 
you tell the assembler the names of the externally defined macro calls 
that appear in the source file. The directive causes the assembler te 
Create entries in its macro symbol table for the macro names and to 
look up the definitions of the related calls in either a user or a 
system macro library. The assembler includes the definitions from the 
library in the module where the calls themselves appear.1l 


1. If you do not include the directive .LIST ME (list macro 
expansions) or .LIST MEB (list macro expansion lines that generate 
object code) in the source file, the assembler does not insert in the 
listing the expanded source code of the macros it assembles. 
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The EXITSS directive (shown in the .MCALL statement) should be in 
every user program for a clean exit. It is the last statement the 
program (task) executes before it returns control to the Executive. 
‘(The EXITSS directive performs important system housekeeping 
operations for the task.) The related definition for EXITSS resides in 
the file RSXMAC.SML in UFD [1,1] on the library device (LB:). DIGITAL 
recommends that user tasks exit by using the EXITSS directive. (An 
alternative form of exiting allows a task to exit and post status.) 


If a call for an externally defined macro statement appears in the 
source file but is not preceded by an .MCALL directive and the macro 
name, the assembler treats the unrecognized macro call as an implicit 
-WORD data storage directive. (If the macro call has parameters, the 
assembler may generate an error because of illegal syntax for a  .WORD 
directive.) Later, when you build the task with the related object 
module and the macro name is not a valid symbol, TKB flags the name as 
an undefined reference. Thus, without the .MCALL directive, the 
assembler does not know that it must search libraries to resolve _ the 
macro symbol. 


2.1.6.6 .END Directive - The .END directive in a module signals’ the 
logical end of source input and optionally specifies the task transfer 
address. The transfer address is the location at which program 
execution begins. Although each source file should contain an .END 
directive, only one source file should define the transfer address. 
The assembler does not process lines beyond the one on which the .END 
directive appears. 


2.1.7 Local Definitions 


In this section of your source file, you collect symbols in direct 
assignment statements. Because symbols in MACRO-11 can be defined as 
expressions of other symbols, having the definitions in one place is 
an advantage. In addition, good programming practice encourages using 
symbols instead of simply supplying a numeric constant. 


For example, in defining a 10-byte buffer, the best method is to 
define a symbol and then use the symbol in the buffer definition. 


LOCAL DEFINITIONS 


Ud se so se 


LOCAL DATA BLOCKS 


(Wwe se we 


UFB: ~BLKB SIZB 
This method has several advantages: 

e If a single constant that is referred to in numerous places in 
the code must be altered, you need perform only one edit (to 
the symbol definition) to effect the change. 


e If all the symbols are gathered in one place in alphabetical 
order, reading the code is simplified. 
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@ You can find all references to a symbol in a cross-reference 
listing. The cross-reference capability allows you to examine 
all the references to a symbol and confidently assess the 
effects of altering the symbol definition. 


These advantages are lost if you use constants. 


Thus, the symbol list would contain such local symbol definitions as 
SIZB = 10. The symbols themselves would appear in the module code. 


2.1.8 Local Macro Definitions 


The definition of a macro statement can appear anywhere in the source 
file as long as the definition appears before the first occurrence of 
the macro statement. It is better programming practice, then, to 
place all macro definitions in a standard place near the front of the 
source file. 


2.1.9 Local Data Blocks 


This section of the source file defines such data as buffers, status 
words, and status bytes. Generally, it describes the local Storage 
that the module references. It is good programming practice to use a 
Separate .PSECT directive for data. See Section 2.1.11. 


2.1.10 Module Function - Detailed 


This section of the source file can be as general or specific as 
needed to describe the functions of the module. A complex module 
should have a lengthy discussion; a simple module need not have as 
much. At aminimum, this section should state the register usage on 
input to and output from the module. 


2.1.11 .PSECT Directive 


The .PSECT directive establishes a name and attributes for a program 
section. A program section is a unit allocation of memory reserved 
for either code or data. For example, you can establish a program 
section to contain data for your program as follows: 


»PSECT DATA,D,RW 


The .PSECT directive creates the program section named DATA with the 
attributes data (D) and read/write (RW). You may give a program 
section for data either the read-only (RO) or the read/write (RW) 
attribute. (The assembler applies other default attributes not 
relevant to this discussion.) 


RSX-11M systems do not support hardware protection of Program sections 
that have the RO attribute. 


RSX-11M-PLUS systems support hardware protection of program sections 


that have the RO attribute if they are in the pure code of a multiuser 
task. 
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Consult the RSX-11M/M-PLUS Task Builder Manual for a discussion of 
program section allocation in multiuser tasks. 


The three most important aspects of the .PSECT directive are: 


@ Contributions defined for a specific program section can be in 
separate places in a source file or in separate source files. 


e The attributes of the program section are passed to TKB. 


e Contributions for a specific program section with the same 
attributes are collected in one continuous allocation of 
memory space by TKB. 


In the skeleton file, it is useful to define one program section to 
contain the data elements referenced in the task and to define another 
program section to contain the code. 


2.2 CREATING A SOURCE FILE FROM A SKELETON FILE 


This section describes how to use an editor, EDI, to create a skeleton 
file and then to create a source file from the skeleton. If you are 
using EDT or some other editor, follow the text for EDI and perform 
the functions using your editor. 


2.2.1 Performing the Initial Input 


To create the skeleton file using MCR, type EDI and the specification 
of a new file, that is, one that is not in your directory. For DCL, 
use the command EDIT/EDI and the specification of a new file. 


Here is the sequence from a DCL terminal: 


DCL>EDIT/EDI SKEL.MAC 
(CREATING NEW FILE) 
INPUT 


Here is the sequence from an MCR terminal: 


MCR>EDI SKEL.MAC 
[CREATING NEW FILE] 
INPUT 


The editor runs, determines that the file does not exist, creates the 
file, and tells you to begin typing the input. 


Type the input according to Example 2-2. Leave any typographical 
errors until after you have become familiar with the editing commands 
described in Section 2.3. The notation conventions appearing in the 
figure are described in the Preface at the front of this guide. 


2.2.1.1 Inserting Blank Lines in Text - To insert a blank line in the 
source file as shown in Example 2-2, type a space or tab on a new line 
followed by the RETURN key. If you type the RETURN key twice in 
succession (that is, type the RETURN key to enter a line of text and 
immediately type the RETURN key again on the new line), EDI terminates 
the input. Thus, to enter a blank line, you need type only one 
nonprinting character, such as TAB, on a new line. 
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2.2.1.2 Terminating the Input and the EDI Program - To terminate the 
input, type the RETURN key twice in succession. EDI prints the 
asterisk to request a command. Type the EXIT command to close the 
file and terminate EDI. For example: 


last line of text © 
* EXIT 
[EXIT] 


> 


When EDI exits, it prints the message [EXIT] and returns control to 
the operating system. The implicit prompt (>) indicates that the CLI 
is ready to accept a new command. The remainder of this chapter makes 
changes in the source file SKEL.MAC and demonstrates EDI commands at 
the same time. If you are using EDT or some other editor, follow the 
changes as demonstrated and make them in your file using your editor. 
If you are using DCL, remember to use the EDIT/EDI or EDIT/EDT 
command. 
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Example 2-2 Creating the Skeleton File SKEL.MAC 


>EDI SKEL.MAC 
CCREATING NEW FILE 


INPUT 

TAB +TITLE CAB SKELTNGADSOURCE FILE 
+ IDENT 78 /01/ 
5 

‘ 

¢ AUTHORS Z 

5 

(AB) GED) 

3 

§ CHANGES; 

5 

AB) GED) 


MODULE FUNCTIONS 


3 

(AB) RED) 

5 

(TAB) +PAGE 

(TAB) eSBTTL SYMBOL» MACRO» 
(TAB) oLIST (49 TTH OB 
»NLIST (4B BEX (49 
«MCALL GB EXITSS 149 
TAB) GED 

5 

§ LOCAL SYMBOL DEFINITIONS: 

j 

GED 

3 

§ LOCAL MACROS: 

5 

CAB) RED) 


ae er 


LOCAL DATA BLOCKS: 


- 


(TAB) +PSECT BATA:DsRW 
(AB) (RET) 

5 

s FUNCTION DETAILS? 
TAB) (RET) 

; 

5 67) INPUTS: 

5 

3) (TAB OUTPUTS: 

5 

te) SIDE EFFECTS! 
; 

(TAB) RET) 

«PAGE 

CAB »SBTTL 

(TAB) »PSECT 

# START CODE HERE 
START: 

(TAB) GED) 

END? 4) EXITSS 149 
«END (5) 
GET) 

EXIT 

CEXITI 


SKELETON 


+ BREAK PAGE FOR PREFACE 
CATA DEFINITIONS 
STERMINAL LISTING MODE 
#SUPPRESS BIN EXTENSION 
sEXEC’S EXIT MACRO 


sEXIT CLEANLY TO EXEC 
*TELL ASSEMBLER END OF CODE 


CREATING MACRO-11 SOURCE FILES 


2.2.2 Creating a Source File from the Skeleton 


After you create the skeleton file, you can use it many times to 
create different source files by running the editor again as described 
in Section 2.2.1. For example: 


MCR>EDI SKEL.MAC 
(00054 LINES READ IN] 
{PAGE 1] 

* 


This time EDI finds the file you just created, reads it into memory, 
and prints an asterisk to request a command. 


The EXIT command with a file specification creates a new file having 
that name and containing all of the text in your skeleton. For 
example: 


*EXIT FILE.MAC 
{EXIT] 


> 


EDI creates either the new file FILE.MAC;1 in your directory or, if 
the file already exists, a new version of the file. It retains the 
input file SKEL.MAC. You can repeat this process to create as many 
new source files as you need. 


At this point, the contents of SKEL.MAC and your new file are exactly 
the same -- typographical errors and all. Now you must use editing 
commands to change your new file to make it unique. Section 2.3 
describes some of these commands and gives examples of their usage to 
enable you to perform the most common editing functions. 


By using the same skeleton file each time you want to create a new 
source file, you save typing time and have a better chance of creating 
consistent, easily readable, and well-documented code. After you have 


gone through Section 2.3 and learned the editing commands, you may 
want to correct the errors in the skeleton file, 


2.3 EDITING THE SOURCE FILE 


This section describes how to use a subset of EDI commands to edit a 
source file. By following the examples in this section, you will 
create three source files that you can use in subsequent stages of the 
program development cycle. 


You can abbreviate most of the commands in EDI. For example, the EXIT 


command can be abbreviated EX. The descriptions of each command 
include (within parentheses) the accepted abbreviation, if one exists. 
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2.3.1 Displaying Text 
Use the EDI command to access a source file to edit. For example: 


MCR>EDI FILE.MAC 
{00054 LINES READ IN] 
[PAGE 1] 

* 


Two keyS, RETURN and ESCAPE, cause EDI to move forward and backward, 
respectively, one line and to display the new line. By using these 
two keys, you can step line by line through a file. For example: 


* GED 

-TITLE SKELTN SOURCE FILE SKELETON 
* ED 

-IDENT /01/ 
* €80 


~TITLE SKELTN SOURCE FILE SKELETON 


Typing the RETURN key twice advances the pointer two times and 
displays each line. Typing the ESCAPE key moves the pointer back to 
the previous line and displays the line. 


TYPE n (TY n) 


The TYPE n command displays n lines at a time but does not alter the 
line position. For example: 


*TYPE 2 
»TITLE SKELTN SOURCE FILE SKELETON 


~IDENT /01/ 
* 


The 2 in the TYPE command causes EDI to display the current line and 
the next line. If you give the TYPE command without a number, EDI 
displays the current line (that is, one line). 


LIST (LI) 


The LIST command displays all lines in the buffer starting at the 
current line and stopping at the last line in the buffer (that is, end 
of buffer). For example: 


*LIST 
(all lines are listed) 
*TYPE 


{*BOB*] 
*EXIT 
(EXIT] 


> 


The LIST command positions the line pointer at the beginning of the 
buffer. The TYPE command shows the position of the line pointer. EDI 
prints the blank line it maintains at the beginning of the buffer and 
the message [*BOB*] to remind you that the line pointer is at the 
beginning of the buffer. EDI always keeps a blank line at the 
beginning of the buffer to allow you to insert lines before the first 
line of text in the buffer. 
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2.3.2 Locating Text and Positioning the Line Pointer 


Editing a file requires you to locate a line of text in the buffer and 
to position the pointer to that line. This section describes several 
of the commands most commonly used in editing files. 


BEGIN (B), END (E) 


The BEGIN and END commands position the pointer to fixed lines in the 
buffer -- the beginning and ending lines. The END command also prints 
the last line of the buffer. For example: 


MCR>EDI FILE.MAC 

[00054 LINES READ IN] 

[PAGE 1] 

*END 

3) .END GS); TELL ASSEMBLER END OF CODE 
* 


The END command is useful for quickly assessing what the last line in 
the buffer is. The BEGIN command is helpful in quickly positioning 
the pointer at the beginning (or top) line of the buffer, thus 
enabling you to make multiple passes over a buffer. For example: 


*BEGIN 
*TYPE 


{*BOB*] 
* 


Because the BEGIN command does not display any text, you can use the 
TYPE command to display the first line in the buffer. The command in 
the example shows the blank line at the beginning of the buffer. EDI 
prints [*BOB*] to show you that it is positioned at the beginning of 
the buffer. For example: 


* GED 
«TITLE SKELTN (8 SOURCE FILE SKELETON 
* 


Typing the RETURN key advances the pointer and displays the line, as 
follows: 


LOCATE (L) 


If the text you want to examine is within the buffer, you can type the 
LOCATE command with a string to be located. For example: 


*LOCATE MODULE 


+ MODULE FUNCTION: 
* 


A space should separate the command and the search string to be 
located. EDI displays the line on which it found the first occurrence 
of the string. If EDI does not find the string, it prints a message 
indicating that the end of buffer has been reached. For example: 


*LOCATE NODULE 
[*EOB*] 
* 
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After an unsuccessful search, EDI leaves the line pointer at the last 
line of the buffer. 


PLOCATE (PL) 


If the string for which you are searching is not in the buffer, you 
can use the PLOCATE command to tell EDI to search successive buffers 
until it locates the string. For example: 


*BEGIN 
*PLOCATE .END 


~ END aS) (4) ; TELL ASSEMBLER END OF CODE 
* 


EDI searches the buffer starting at the current line. if the string 
is not found in the buffer, EDI preserves the contents of the buffer 
and reads in more lines from the input file to fill the buffer again. 
It prints a message telling the number of lines searched. When EDI 
finds the string, it displays the line on which the string occurs. If 
EDI does not find the string, it prints a message indicating that the 
end of file has been reached. For example: 


*PLOCATE .ENDR 
[*EQOF*] 
* 


At the end of file (signaled by [*EOF*]), EDI leaves an empty buffer 
in which you can either insert new text (which follows all the text 
currently in the file) or exit to preserve any changes made and _ to 
start at the beginning of the file again. Note that, once EDI has 
preserved a buffer, you cannot go back to it except by starting at the 
beginning of the file again. For example: 


*EXIT 
[EXIT] 


> 


You can also use the PLOCATE command with a string known not to exist 
in the file to position EDI after the last line of the file. 


RENEW (REN) 


The RENEW command lets you read new lines from the input file. For 
example: 


*EDI FILE.MAC 

{00054 LINES READ IN] 
{PAGE 1] 

*RENEW 

{ *EOF*] 

{PAGE 2] 

*EXIT 


[EXIT] 

> 
The RENEW command writes the lines in the buffer to the temporary 
output file before it reads in new lines from the input file. If 


there are no more lines left in the file, EDI signals the end of file. 
This command is useful for casually inspecting the contents of a file. 
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2.3.3 Changing Text 
CHANGE (C) 


The CHANGE command alters text on the current line, allowing you to: 
1. Replace an old string with a new string 
2. Add a string at the start of a line 
3. Delete a string from a line 


The command requires that you type, within character delimiters, the 
old string (the text to be altered) followed by the new string. The 
only requirement for the delimiting character is that it does not 
appear in either the old or the new string.1 A convenient character to 
use as a delimiter is the slash character (/), as shown in the 
following example: 


MCR>EDI FILE.MAC 
{00054 LINES READ IN] 
[PAGE 1] 
* GD 
- TITLE SKELTN SOURCE FILE SKELETON 
*C /SKELTN/NUMA/ (ED 
-TITLE NUMA SOURCE FILE SKELETON 


After you enter the c command, EDI searches the line for the old 
String (SKELTN) and replaces it with the new string (NUMA). EDI then 
prints the changed line to allow you to verify the operation. If EDI 
cannot locate the old string, it prints the message [NO MATCH] and 
reprints the prompt. 


To save typing long strings, EDI allows you to include an ellipsis 
(...) in the old string. For example: 


*C /SO...ON/COUNT NUMBER OF A'S/ 


- TITLE NUMA COUNT NUMBER OF A'S 
* 


EDI takes the characters $0, all intervening characters, and the 
characters ON as the old string. The ellipsis, used in this manner, 
reduces the amount of typing required to specify a string to be 
changed. Three other forms of the ellipsis allow variations of the 
abbreviation: 


fooe/ By itself, the ellipsis means the entire line 
fold string.../ From old string to the end of the line 
/os-01d string/ From the beginning of the line to old string 


The slash characters shown as delimiters with the ellipsis can be any 
unique character. 


1. The ampersand character (&) should not be used as a delimiter 
because EDI treats it as a concatenation character. If you must use 
it as a delimiter, follow the special procedures presented in the EDI 
chapter in the RSX-11M/M-PLUS Utilities Manual for using the 
Concatenation Character (CC) command. 
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To place a string at the beginning of a line, specify the null string 
as the old string. For example: 


*C //OLD STRING/ @) 


OLD STRING A) .TITLE NUMA 43) COUNT NUMBER OF A'S 
* 


EDI replaces the null string at the beginning of the line with OLD 
STRING and prints the changed line. 


To delete a string from the line, specify the null string as the new 
string as follows: 


*C /OLD STRING// GED 


(TAB) -TITLE 3 NUMA 43) COUNT NUMBER OF A‘S 
* 


EDI replaces OLD STRING with the null string: that is, it deletes OLD 
STRING and prints the changed line. 


AP 


A special command, AP, adds a string at the end of a line. The 
command does not need delimiting characters since only one string can 
be specified. Simply specify a space to separate the command and _ the 
string as follows: 


* (ED 
~IDENT /01/ 
*AP (A) ; IDENTIFY MODULE VERSION 


-IDENT /Ol/ ‘TAB ; IDENTIFY MODULE VERSION 
* 


After adding the text at the end of the line, EDI displays the changed 
line. 


DP n 


To remove a line or lines from the text in the buffer, specify the 
DP n command, where n is the number of lines to be deleted. You can 
use the TYPE n command with the DP n command to display the lines to 
be deleted. For example: 


*TYPE 3 


~e we 


; AUTHOR: Z 
*DP 2 


; AUTHOR: Z 
* 


The TYPE 3 command displays the current line and two succeeding lines 
(the pointer remains positioned at the current line). The DP 2 
command deletes the current line and one succeeding line. EDI moves 
the pointer to the line after the last one deleted and prints that 
line. 
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EXIT (EX) 


After changing text in the file, close the editing session, as 
follows: 


*EXIT 
[EXIT] 


> 


The EXIT command without a file name creates a new version of the 
current file and copies the remainder of the file to the new version. 
Because exiting preserves the edits you have made to that point, you 
should exit fairly often from a lengthy editing session. If a system 
crash occurs, EDI retains the old version of your file (that is, it 
retains the edits up until you last exited) but does not retain the 
changes you are making. Frequent exits minimize the amount of editing 
that can be lost if a system crash occurs. 


2.3.4 Inserting Code in the Source File 
INSERT (I) 


The INSERT, or I, command allows you to add multiple lines of text in 
the source file. To insert code in the source file FILE.MAC, use 
positioning commands to locate the line preceding where you want to 
place the new material. The I command places new lines in the buffer 
after the current line. For example: 


MCR>EDI FILE.MAC 
{00052 LINES READ IN] 
[PAGE 1] 

*L, FUNCTION: 

+ MODULE FUNCTION: 


*I GED 

; THIS MODULE LOADS A BUFFER, 

H COUNTS THE NUMBER OF A'S (UPPER 

: CASE ONLY) IN THE BUFFER, CONVERTS 
7 THE NUMBER TO OCTAL, AND REPORTS 

; THE NUMBER OF A'S FOUND. (& 

ad 


The L command (for LOCATE) positions EDI to the line preceding where 
you want to place the new lines. Typing the I command followed by the 
RETURN key places EDI in insert mode. After you type the lines, press 
the RETURN key twice in succession to leave insert mode. 


Continue using positioning and editing commands to type in the 
remainder of the source program shown in Example 2-3. 
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a GP iP UP 


> we cer 


a> a> a “Gh “OP “eb WP Or 


; 
$ LOCAL 


ad 


LOCAL 


“a> “aD “ep 


LOCAL 


a> “=> “ae 


oe 
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Example 2-3 Source Code for FILE.MAC 


+TITLE NUMA COUNT NUMBER OF A‘S 
»IDENT /01/ + IDENTIFY MODULE VERSION 


AUTHOR: Z 


CHANGES? 


MODULE FUNCTION: 


THIS MODULE LOADS BUFFER» 

COUNTS THE NUMBER OF A‘S (UPPER 
CASE ONLY) IN THE BUFFER» CONVERTS 
THE NUMBER TO OCTAL» AND REPORTS 
THE NUMBER OF A‘S FOUND. 


+PAGE § BREAK PAGE FOR PREFACE 
sSBTTL SYMBOL» MACRO, DATA DEFINITIONS 

«LIST TTM $ TERMINAL LISTING MODE 

»NLIST BEX 3 SUPPRESS BIN EXTENSION 
»MCALL EXIT$S $ EXEC’S EXIT MACRO 


SYMBOL DEFINITIONS: 

MSGLEN = NUMEND-MSG 
SIZ = 80. 
SIZA = 6. 


MACROS? NONE 


DATA BLOCKS; 


*PSECT DATA» DsRW 


*ASCII /A/ 3 DEFINE AN A 

«BLKE Siz 3 DEFINE BUFFER 

+ASCII /THE NUMBER OF A‘S IS / 

+BLKE SIZA ¢ DEFINE OCTAL COUNT 

= ¢ END OF MESSAGE 

«BLKW 1 } NUMBER OF CHARS TYPED 
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Example 2-3 (Cont.) Source Code for FILE.MAC 


FUNCTION DETAILS: 


INPUTS 
BUFi IS LOADED WITH CHARACTERS 


OUTPUTS! 
NUMA HOLDS THE NUMBER OF A‘S 


SIME EFFECTS! NONE 


ah “EP EP E> ee ep OP “oP 


§ START CODE HERE 


CALL WRITE 
END: EXITSS 


REPORT THE RESULTS 
EXIT CLEANLY TO EXEC 
TELL ASSEMBLER END OF CODE 


+PAGE 
*SBTTL ROUTINE TO COUNT A‘S 
+PSECT 
STARTS 
mov #BUF1»RO ¢ LOAD BUFFER ADDR 
MoV #SIZeRi * LOAD BUFFER SIZE 
CALL READ + READ FROM TTY 
TST R2 ’ ANY CHARS IN BUFFER? 
BEQ END 3 IF NONE> FINISH UP 
CLR Ri > INIT # OF A‘S COUNTER 
MOV R2»NUMC * SAVE # OF CHARS TYPED 
1083 
CHB CROFT + IS CHAR = A? 
BNE 20% * IF NOs BET NEXT CHAR 
INC R1 3 COUNT AN A 
208% 
DEC R2 + ONE LESS CHAR 
BNE 10% * IF MORE? COMPARE NEXT 
«PAGE 
+SETTL TRANSLATE COUNT TO OCTAL 
MOV #NUMATE*RO * SET PTR TO OCTAL # 
MaYV #59R2 § SET COUNT OF DIGITS 
308: 
Moy Ri;s-(SP> + STACK IS TEMP AREA 
BIC #177770,78SP 3 STRIP LOW 3 BITS 
AnD #607@SP 5 MAKE OCTAL DIGIT 
MOVE (SP) +e-CRO) 3 STORE OCTAL DIGIT 
ASR Ri * SHIFT TO 
ASR Ri ; NEXT 
ASR Ri 3 3 BITS 
BEC R2 ¢ ONE LESS DIGIT 
BNE 30% * IF MORE, REPEAT 
MoV #MSGrRO * LOAD ADDR OF BUFFER 
MOV #MSGLEN?R1 § LOAD SIZ OF MESSAGE 
; 
3 
; 
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After you have typed in the code, use the techniques described 
previously to create two new source files, FILEA.MAC and FILEB.MAC, 
from the skeleton file. The code for these two files is shown in 
Examples 2-4 and 2-5. These two files and the file FILE.MAC will be 
used in Chapter 4 to build and test a task. You may want to edit the 
skeleton file before you create the two new Source files. 


Example 2-4 Source Code for FILEA.MAC 


*TITLE TTREAD TERMINAL READ SUBROUTINE 
+IDENT /017 


AUTHOR: DEF 8-AUG-81 


we uP ep 


CHANGES? NONE 


ee 


MOBULE FUNCTIONS 
THIS MODULE READS A LINE FROM A 
TERMINAL INTO A BUFFER 


<er ses Ue er 


“ar 


» PAGE s BREAK PAGE FOR PREFACE 
*SBTTL SYMBOL» MACRO» DATA DEFINITIONS 

+LISt TT § TERMINAL LISTING HODE 
»NLIST BEX 5 SUPPRESS BIN EXTENSION 


oMCALL QIOSS,WTSESS 


NITIONS? 
EFNI 


LOCAL SYHBOL DEF 
LUNS = 


T 
1 
S 


; 
5 LOCAL MACROS? NONE 
; 


; 
* LOCAL DATA BLOCKS? 
; 
«PSECT DATA De RW 


Tost: +BLKW 2 ’ DEF IO STATUS WOS 
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Example 2-4 (Cont.) Source Code for FILEA.MAC 


FUNCTION DETAILS: 


INPUTS! RO = ADDRESS OF BUFFER TO LOAD 
Ri = LENGTH IN BYTES OF BUFFER 


OUTPUTS! R2 = NUMBER OF CHARS (BYTES) READ 
SIDE EFFECTS! IOT IF ERROR 


Se “GP ae Wh “EP ep 88 


+PAGE 
*SBTTL START OF CODE 
+PSECT 
§ START CODE HERE? 
READ? $ * DEFINE ENTRY POINT 


Qross #IO.RLBs $LUNS»s SEFN1 + 2p OLOSTs ep <ROPRI> 
QIO DIR PARAMETERS? 
RLB IS READ LOG BLOCK 
LUNS = TKB DEFAULT 
EFN1 IS EVENT FLAG #1 
IOST = STATUS AREA 
<> = PARAMETER LIST 
RO START OF BUFFER 
Ri SIZE OF BUFFER 
IF SET, DIR ACCEPT ERROR 
WAIT FOR ITO COMPLETE+EF 1 
CHECK 10 STATUS 


BCS 10$ 
WTSE$S #&FN1 
TSTB Tost 


ep Oh er EP me OD OP > OR Re ee ee 


BLT 10% IF LTs I0 ERROR 
MOY TOST+22R2 SAVE # OF BYTES READ 
RETURN GO BACK TO CALLER 
10$: 
MOV $DSW,RO * SAVE DIR STAT WD 
MOUB TOSTsR1 § SAVE TO STAT BYTE 
IoT + FORCE SST EXIT 
»END ’ TELL ASSEMBLER END OF CODE 
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Example 2-5 Source Code for FILEB.MAC 


«TITLE TTWRIT TERMINAL WRITE SUBROUTINE 
«IDENT /01/ 


AUTHOR? DEF 8-AUG-81 


ws “+ we 


CHANGES: NONE 


a> ae we 


MODULE FUNCTION: 


THIS MODULE WRITES A 
LINE FROM A BUFFER TO 


“2> ar “> er “a> “ar 


& TERMINAL 

3 F 
«PAGE ¢ BREAK PAGE FOR PREFACE 
+SBTTL SYMBOL» MACRO, DATA DEFINITIONS 
«LIST TTM + TERMINAL LISTING MODE . 
»NLIST BEX s SUPPRESS BIN EXTENSION 


+MCALL QIOSS*WTSESS 


5 

¢ LOCAL SYMBOL DEFINITIONS: 
EFN1 = 1 
LUNS = 5 


3 
# LOCAL MACROS! NONE 
; 
; 
§ LOCAL DATA BLOCKS; 
3 


+PSECT DATAsD RW 


OST: »BLKW 2 3 DEF 10 STATUS WDS 


ses ap bt 


FUNCTION DETAILS$ 

INPUTS: 
RO = ADDR OF BUFFER TO WRITE 
Ri = LENGTH IN BYTES OF BUFFER 
OUTPUTS: 


success IN IOSsT 
SIDE EFFECTS! IOT IF ERROR 


a> OP Eh ap ah ee ee er ee 
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Example 2-5 (Cont.) Source Code for FILEB.MAC 


» PAGE 
*SBTTL START OF CODE 
»PSECT 
§ START CODE HERE 
WRITES? + DEF ENTRY POINT 
aQrass FIO.WLBs SLUNS re tEFN1 sp €IOSTs eo <ROPR1» $40> 
QIO$S PARAMETERS: 
IO.WLB FUNCTION CODE 
LUNS ¢(TKB DEFAULT) 
EFN1 IS EVENT FLAG 1 
STATUS AREA = IOST 
PARAMETER LIST <> 


RO = START OF BUFFER 
Ril = # OF CHARS TO WRITE 
40 = OUTPUT <CR>?<LF> 


BCS 10 
WISESS #EFNI 
TSTB IOST 


IF SET» DIR ACCEPT ERROR 
WAIT FOR IO COMPLETE 
CHECK IO STATUS 


“OP “OF “GF Eb ‘ah EP ED ED “EP eh ae ae aD “Se 


BLT 10% IF LT» IO ERROR 
RETURN GO BACK TO CALLER 
10$3 
MOV SISWH»RO * SAVE DIR STAT Wh 
MOVB TOSTsR1i 3 SAVE IO STAT VALUE 
IOT + SST DUMPS TASK REGS 
»END § TELL ASSEMBLER END OF CODE 


2.4 GUIDE TO FURTHER READING 
The sections or chapters in the following documents contain additionai 
information on the subjects described in this chapter. 
Document 
PDP-1i MACRO-11 Language Reference Manual 
Chapter 2, Source Program Format 
Appendix E, Sample Coding Standard 
Section 6.1, Listing Control Directives 
Section 6.6, Terminating Directives 
Section 6.7, Program Sectioning Directives 
Section 7.8, MACRO Library Directive: .MCALL 
RSX-11M/M-PLUS Task Builder Manual 
Section 2.1, Linking Object Modules 
Section 10.1.28, SG (Segregate Program Sections) 
Section 10.1.32, SQ (Sequential Program Sections) 
RSX~11M/M-PLUS Utilities Manual 
Chapter 2, Line Text Editor (EDI) 
RSX-11M/M-PLUS Executive Reference Manual 
Section 1.4.1, Macro Name Conventions 


Chapter 5, Task Exit (EXITS$S) 
Chapter 5, Queue I/O Request and Wait 
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CHAPTER 3 


ASSEMBLING AND CORRECTING A PROGRAM MODULE 


This chapter describes a few uses of the MACRO-1l Assembler, some of 
the common types of coding errors, some ways to uncover and correct 
errors, and the way to generate a cross-reference listing. 


The material in this chapter assumes that you have created the three 
source files as described in Chapter 2. 


3.1 PERFORMING A DIAGNOSTIC RUN ON A SOURCE FILE 


Your first use of the MACRO-11 Assembler on a source file should be to 
perform a diagnostic run. You run the assembler only to check for 
general errors, not to produce an object module or a listing file. 


To perform a diagnostic run from a DCL terminal, type the following 
command line: 


DCL>MACRO/NOOBJECT/DISABLE:GLOBAL FILE 
(any error messages appear) 
> 


The source file is named FILE.MAC, but because the MACRO command 
defaults to a file type of MAC, the file type need not be specified. 
Normally, the MACRO command is used to create an object module, so 
that the /NOOBJECT qualifier is necessary to override this standard 
function. The MACRO command does not produce a listing file unless 
you request one with the /LIST qualifier. When you do not make a 
listing file, any errors that result from assembly are listed directly 
on your terminal. 


The /DISABLE:GLOBAL qualifier causes MACRO-11 to disable the setting 
of undefined symbols to global and external. Ordinarily, when 
MACRO-11 finds a symbol that is not defined in the source file, it 
assumes that the reference is to a symbol defined externally, that is, 
in another module. By disabling this feature for your diagnostic run, 
you teli the assembier to flag any potential giobal references as an 
undefined symbol error. Since you already know which symbols in your 
source file are global, this disabling method is a convenient way to 
catch typographical errors in other symbol names. 


To perform a diagnostic run from an MCR terminal, type the following 
command line: 


MCR>MAC /DS:GBL=FILE 


(any error messages appear) 
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The right side of the equal sign gives the specification of the source 
file. The assembler searches for the file named FILE.MAC in your UFD. 
The assembler applies the type MAC as a default. Because there are no 
file specifications on the left side of the equal sign, MACRO-11 does 
not produce any object module or listing file. When you do not 
specify a listing file in the command line, the assembler prints on 
the input terminal the lines that generated errors and reports. the 
total number of errors found. 


The left part of the command line (/DS:GBL) causes MACRO-11 to disable 
the setting of undefined symbols to global and external. Ordinarily, 
when MACRO-11 finds a symbol that is not defined in the source file, 
it assumes that the reference is to a symbol that is defined external 
to the module (in another module). (The notation GX in the listing 
symbol table denotes a global and externally defined symbol.) By 
disabling this feature in the diagnostic run, you tell the assembler 
to flag any potential global reference with an undefined symbol error. 
This disabling method is a convenient way to catch typographical 
errors in symbol names at assembly time rather than later when you 
link your object modules together. 


The appearance of MACRO-11 messages at the terminal during the 
diagnostic run indicates that your module contains errors. If the 
assembler does not find any errors, it simply returns control to the 
Executive and MCR prints its prompt. Errors in the assembly are 
denoted by single letter codes printed at the beginning of the faulty 
statement. These errors are summarized in an appendix of the PDP-11l 
MACRO-11 Language Reference Manual. 


The only errors that should appear from the diagnostic run are the 
following: 


U 71 000010 004767 CALL READ 
U 99 000110 004767 CALL WRITE 
ERRORS DETECTED: 2 

/DS:GBL=FILE 


READ FROM TTY 
REPORT THE RESULTS 


=e Ne 


The two undefined symbols READ and WRITE are the entry points defined 
in the source files FILEA.MAC and FILEB.MAC. These symbols are to be 
resolved by TKB. (Note that this example was generated by the MCR 
command MAC /DS:GBL=FILE.) 


3.2 TYPICAL ERRORS ENCOUNTERED DURING ASSEMBLY 


Four error codes cover the majority of errors made in an assembly 
language source file. The following sections describe some of the 
most common conditions under which these error codes are generated. 


3.2.1 The MACRO-11 Error Code A 


Error code A indicates a general assembly error. Most of these errors 
are caused by typing mistakes such as the following: 


e Omitting the semicolon (;) from a comment 


The semicolon separates your comment from the portion of the 
statement that the assembler evaluates. If you omit the 
semicolon, MACRO-11 attempts to evaluate your comment as part 
of the rest of the statement line. 
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e Omitting the period from a MACRO-11 directive 


The leading period (.) in the operator field tells the 
assembler that the statement contains a MACRO-11 directive. 
If you forget to include the period on a directive, the 
assembler cannot evaluate the operator as a directive. As a 
result, error code A is generated, the directive and its 
arguments are given a value of 0, and they are designated as 
global symbols. 


e Misspelling a PDP-11 instruction mnemonic 


If you misspelled a PDP-11 instruction mnemonic (for example, 
MOVE instead of MOV), the assembler can evaluate the operands 
but not the operator. The PDP-11 MACRO-11 Language Reference 
Manual lists all the mnemonics alphabetically. (These 
mnemonics make up the permanent symbol table (PST)). The 
PDP-11 Programming Card also contains all the instruction 
mnemonics. 


e Forming an illegal symbol 
The first character of a symbol must not be a numeral. 
e Not properly delimiting a directive argument 


Many MACRO-11 directives require a character or argument 
string to begin and end with a certain delimiting character. 
If you use the wrong character or omit one of the delimiters, 
the assembler cannot properly match the delimiters and 
therefore cannot evaluate the directive. For example, the 
-ASCII directive requires the character string to begin and 
end with the same delimiting character. 


Another type of general assembly error involves general addressing 
errors. The typical addressing error is to exceed the range of a 
branch instruction (that is, branching more than 128 words backwards 
or 127 words forwards). To correct this type of error, replace the 
branch instruction with code to test the proper condition, and with 
the JMP instruction to transfer control. 


Also common as a general assembly error are illegal forward 
references. If you define a symbol based on another symbol defined by 
a forward reference, the assembler cannot evaluate the reference. For 
example: 


A 
Cc 


B+ 10. 
A + 10. 


The assembler cannot evaluate the symbol A because B is not yet 
defined. 


3.2.2 The MACRO-11 Error Code U 


Error code U signals an undefined symbol error. This error usually 
occurs because (1) a symbol name on the .MCALL directive was 
misspelled or, (2) reference was made to a local label that does not 
exist in the current local symbol block. 
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3.2.3 The MACRO-11 Error Code Q 


Error code Q indicates questionable syntax. This error usually 
results from either including too many (or too few) arguments in a 
directive or specifying an incorrect number of operands on an 
instruction. In addition, this error occurs when you omit the 
semicolon from a comment and the assembler attempts to evaluate the 
comment as part of the statement. 


3.2.4 The MACRO-11 Error Code E 


Error code E means that you have omitted the .END directive from the 
assembly language source file. If the assembler does not find the 
-END directive, it generates error code E with a line number of 0 
after the last statement in the listing file. 


Error code E also may indicate an expression overflow. If the 
assembler encounters a nested expression that is too complex, it 
generates error code E and denotes the point of the overflow with a 
question mark (?). To clear the error condition, either simplify the 
expression or ask your system manager to build MACRO-11 with a larger 
stack. 


3.3 GENERATING A PROGRAM MODULE AND A LISTING 


After you correct the errors uncovered in the diagnostic run, you are 
ready to produce an object module and a listing file. The following 
DCL command line produces an object module and a listing file: 


DCL>MACRO FILE/LIST 
(error summary printed) 
> 


This command line, like the command line for the diagnostic run, 
assumes default file types for the object file and the listing file. 
The assembler creates an object module called FILE.OBJ. The /LIST 
qualifier causes the assembler to create a file called FILE.LST, It 
is good programming practice to use the assembler defaults for file 
types and file names. Using the defaults helps you differentiate file 
types and groups associated files under the same name. If you wish to 
use other names and file types, you can override the defaults by 
Supplying complete file specifications as arguments to the /LIST and 
/OBJECT qualifiers. 


Note that the /LIST qualifier is added to the file specification 
rather than to the MACRO command in the example. This placement of 
the qualifier causes a listing file to be created in your directory, 
but the file is not printed on the line printer. A MACRO command line 
in the following format: 


DCL>MACRO/LIST FILE 
(error summary printed) 
> 


Still causes the listing file FILE.LST to be created in your 
directory, but the file is also printed on your system's line printer. 
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For the time being, you should use the /LIST qualifier as a file 
specification qualifier, to keep from printing too many copies. 
During the program development cycle, you create many files for which 
you do not need a permanent copy. it is easier and less wasteful to 
examine a listing file at your terminal than to generate numerous 
printed copies of listing files that must be discarded because of 
minor errors. After you attain an error-free assembly, you can print 
a copy of the latest version of the listing file. 


When you request a listing file, the errors are printed in the file, 
not on your terminal. All you see on your terminal is a message 
giving the total number of errors found. If no message appears, there 
are no errors. Note, however, that freedom from assembly errors does 
not guarantee that the program will run properly. 


The following command line performs the same functions from an MCR 
terminal: 


MCR>MAC FILE,FILE/-SP=FILE 
(error summary printed) 
> 


This command line, like the command line for the diagnostic run, 
depends on default file types that MACRO-11 automatically assigns. 
The leftmost file specification creates an object module called 
FILE.OBJ. The file type OBJ denotes that the file is an object 
module. 


The comma following the object file specification in the command line 
is a separating character that is required to distinguish different 
file specifications in command lines. 


Following the comma in the command line is the listing file 
specification that creates the file called FILE.LST. The file type 
LST denotes that the file is a listing of source code produced by an 
assembler or compiler. 


It is good programming practice to use the assembler defaults for file 
types and to apply the name of the source file to both the object and 
listing files. Using the defaults helps you to differentiate types of 
files and keeping the same name helps relate different types of files 
to the proper source file. 


The designation /-SP following the listing file specification in the 
command line inhibits automatic spooling of the listing to the line 
printer. During the program development cycle, you create many files 
for which you do not need a permanent copy. It is easier and less 
wasteful to examine a listing file at your terminal than to generate 
numerous copies of listing files that must be discarded because of 
minor errors. After you attain an error-free assembly, you can spool 
a copy of the latest version of the listing file retained on your 
disk. 


When you request a listing file in the assembly, MACRO-11 does not 
print error lines on the terminal. Instead, if the assembler detects 
any errors, it prints a message giving the total number found. If the 
assembler finds no errors, it simply exits. The absence of a summary 
of error messages from the assembler means an error-free assembly. If 
there are errors, you can examine the listing file at the terminal. 
However, an error-free assembly does not guarantee that the program 
will run properly. 
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You can issue the following command lines to assemble the two other 
Source files, FILEA,MAC and FILEB.MAC, which you created using the 
procedures described in Chapter 2: 


DCL>MACRO FILEA/LIST 
DCL>MACRO FILEB/LIST 


or 


MCROMAC FILEA, FILEA/-SP=FILEA 
MCR>MAC FILEB,FILEB/-SP=FILEB 


The two command lines create the object modules FILEA.OBJ and 
FILEB.OBJ that you will need to link into your task in Chapter 4. 


3.4 EXAMINING A LISTING AT THE TERMINAL 


Use the TYPE command to display the listing file at your terminal, as 
shown: 


DCLOTYPE FILE.LST 
(file appears on screen) 
> 
From an MCR terminal, you can run the Peripheral Interchange Program 
(PIP) to transfer a copy of your listing from your disk to your 
terminal. The following command line starts the transfer: 


MCR>PIP TI:=FILE.LST 


(file 


sy 


ppears on screen} 
> 


In the part of the command line to the left of the equal sign, the 
designation TI: specifies your terminal (that is, the terminal 
initiating the request) as the output device. 


NOTE 


If you omit the colon from TI:, PIP 
creates a new file called TI in your UFD 
and copies the input file to it. 


To the right of the equal sign is the input file specification with 
both a name and type. For PIP, you must specify a file type because 
it does not apply a default file type for you. (Without a file type, 
PIP looks for a file with no type, that is, a file with a null type.) 


You can use control commands to temporarily stop and restart the 
display, and to alternately suppress and resume the output request. 
The commands are summarized in Table 3-1. 
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Table 3-1 
Terminal Output Control Commands 


Temporarily stops the display 


Restarts the display stopped by CTRL/S 


Alternately suppresses and resumes 
the output to the terminal 


The CTRL/S and CTRL/Q commands are used together to freeze the display 
on the screen and to request more lines to be displayed. While the 
CTRL/S command is in effect, you can read what is on the screen. The 
CTRL/Q command tells the system to restart the display where it left 
off when it sensed the CTRL/S command. 


The CTRL/O command is used to suppress unwanted output. The command 
tells the system to stop sending characters to the terminal. The 
program, however, continues processing but simply omits displaying the 
output. (While CTRL/O is in effect, the system disables keyboard 
input and does not echo any characters typed at the terminal.) By 
typing CTRL/O again, you tell the system to resume output to the 
terminal. By typing successive CTRL/Os, you can skip unnecessary 
portions of the output until the program reaches the correct part. If 
the program finishes processing the output request while CTRL/O is in 
effect, the system automatically reenables keyboard input and a prompt 
appears on the terminal. 


3.5 GENERATING A CROSS-REFERENCE LISTING 


Worthwhile additions to the assembly listing are the symbol and macro 
cross-reference listings. These listings give, in alphabetical order, 
each symbol and macro name defined or referred to and the number of 
the page and line in the listing where the definition or reference 
occurs. From a DCL terminal, type the following command line: 


DCL>MACRO/NOOBJECT FILE/CROSS_REFERENCE 
(any errors cause total number to be printed) 

> 
Note that the command line does not include the /LIST qualifier. The 
/CROSS_ REFERENCE qualifier implies the /LIST qualifier since the 
cross-reference listing is attached to the assembly listing. If you 
wish to have the listing printed, use /CROSS REFERENCE as a command 
qualifier instead of as a file qualifier. 
Remember, you do not need to type the full form of the command unless 
you are keeping a record of terminal activity. The following command 
line has the same effect as the one above: 


DCL>MAC/NOOB FILE/CR 
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From an MCR terminal, you generate the cross-reference listing by 
typing the following: 


MCR>MAC ,FILE/CR/-SP=FILE 
(any errors cause total number to be printed) 
> 


Because no file specification precedes the comma in the command, 
MACRO-11 omits creating the object module and produces only a listing 
file. The /CR designation tells the assembler to generate a request 
for the CRF task to produce a cross-reference listing. (Omitting the 
comma from the command causes an error because the command then 
requests an object module only. With an object module specification, 
the designations /CR and /-SP are illegal.) 


NOTE 


If, after you request a cross-reference 
listing, you discover that the 
information is missing from your 
listing, the CRF task is either not 
installed on your system or still 
Processing the request. Ask your system 
manager to install the CRF task, 


The CRF task appends the cross-reference listing to the end of the 
listing file, denoting the cross-references by the titles SYMBOL CROSS 
REFERENCE and MACRO CROSS REFERENCE. 


3.6 SPOOLING A COPY OF LISTINGS 


Once you have developed an error-free assembly, you can obtain a hard 
copy of the listing for reference. From a DCL terminal, type one of 
the following command lines: 


DCL>PRINT FILE.LST 
> 


or 


DCL>MCR PIP FILE.LST/SP 
> 


The command lines create a request to the spooling task to print the 
file you specify. (You can specify more than one file at a time by 
listing more than one file specification in the command line, 
Separating each with a comma.) Your request is placed in a queue of 
requests. 


If your system does not have spooling, you can list the file directly 
on the printer, as follows: 


DCL>MCR PIP LP:=FILE.LST 
> 


If the printer is not busy or allocated by another user, PIP outputs 
the file to LPO:. 
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The process for obtaining a hard-copy listing is very similar from an 
MCR terminal. 
From an MCR terminal, type one of the following command lines: 


MCR>PRINT FILE.LST 
> 


or 


MCR>PIP FILE.LST/SP 
> 


The command lines create a request to the spooling task to print the 
file you specify. (You can specify more than one file at a time by 
listing more than one file specification in the command, separating 
each with a comma.) Your request is placed in a queue of requests. 


If your system does not have spooling, you can list the file directly 
on the printer, as follows: 


MCR>PIP LP:=FILE.LST 
> 


If the printer is not busy and is not allocated by another user, PIP 
outputs the file to LPO:. 


3.7 CLEANING UP THE DISK DIRECTORY 
After you edit and reassemble the source files several times, your 
directory becomes cluttered with multiple versions of the same files. 
DCL includes a DIRECTORY command for listing information about files. 
The following command lists all the files in your directory: 

DCL>DIRECTORY 

(the directory listing appears) 

> 
You will notice in the directory a number of files with the same name 
and type, but different version numbers. Use the following command to 
purge all but the most recent version of these files: 

DCL>PURGE *.MAC,*.LST,*.OBJ 
From an MCR terminal, you can list the name, types, version numbers, 


and sizes of the files stored in your UFD by typing the following 
command line: 


(the directory listing appears) 
> 
The designation /LI causes PIP to list the directory information at 


your terminal. By default, the command line requests all names, 
types, and versions of files in your UFD. 
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By examining the directory information, you notice that files with the 
same name and type have multiple versions. Use the following command 
line to the PIP program to purge all but the most recent version of 
the files: 


MCR>PIP *.MAC,*.LST,*.OBJ/PU 
> 


The designation /PU purges all but the latest version of the files 


specified. The asterisk character in the command denotes all files 
having any name and the type specified. 


3.8 GUIDE TO FURTHER READING 
The sections or chapters in the following documents contain additional 
information on the subjects described in this chapter. 
Document 
RSX-11M/M-PLUS Command Language Manual 
Section 6.2.1, MACRO Command 
PDP-11 MACRO-11 Language Reference Manual 
Chapter 8, IAS/RSX-11M/RSX-11M-PLUS Operating Procedures 
8.1.1, Default File Specifications 
8.1.2, MCR Command String Format 
8.1.2.1, MCR File Specification Switches 
8.1.3, DCL Operating Procedures 
8.5, MACRO-11 Error Messages Under IAS/RSX-11M/M-PLUS 
Appendix D, Error Messages 
RSX-11M/M-PLUS Utilities Manual 


Chapter 3, Peripheral Interchange Program (PIP) 
Appendix B, The Cross-Reference Processor (CRF) 


es 


Chapter 2, Queuing Jobs 
Section 2.1, PRINT Command 
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BUILDING AND TESTING A TASK 


This chapter describes ways to use the Task Builder (TKB) program to 
create a task image from program object modules. The procedures 
described in this chapter assume that you have created three 
error-free object modules as described in Chapter 3. 


4.1 CREATING A TASK IMAGE 


The TKB program creates a task image file that can be loaded into 
memory. You can supply as input to TKB either a single object module 
or multiple object modules. In most cases, however, your programs 
will consist of multiple object modules. The following sections 
describe the procedures and the way TKB reports error conditions. 


4.1.1 Supplying a Single Object Module 


Use the DCL LINK command to create a task image file from a_ single 
object module: 


DCL>LINK FILE 
(any error messages appear) 
> 


Once again, all defaults are applied automatically. The LINK command 
defaults to an object module in a file named FILE.OBJ and causes TKB 
to produce a file named FILE.TSK containing the task image. 


To perform the same function from an MCR terminal, enter the following 
command line: 


MCROTKB FILE=FILE 
(any error messages appear) 
> 


The right side of the equal sign specifies the file containing the 
object module. TKB assumes that the type in the file specification is 
OBJ. The left side of the equal sign gives the specification of the 
task image file to which TKB assigns the file type TSK. Again, as 
with the assembler, it is convenient to apply the same name to both 
the output file and the input file and to let TKB apply the default 
type specifications. 
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TKB tries to resolve all global references in the object module. If 
there are undefined references after the module has been processed, 
TKB searches the system object library SYSLIB.OLB in UFD [1,1] on the 
library device (LB:). If no errors are encountered in the process, 
TKB exits and the command prompt (>) appears. 


If TKB detects an error during processing, it prints a message at the 
terminal in one of the following forms for MCR users: 


TKB -- *DIAG* ~ error message 
or 
TKB -~ *FATAL* - error message 


If TKB detects an error during processing, it prints a message in one 
of the following forms for DCL users: 


LINK -- *DIAG* - error message 
or 
LINK -- *FATAL* - error message 


TKB error messages are summarized in the RSX-11M/M-PLUS Task Builder 
Manual. 


If an error message appears and the error condition described is not 
operational (for example, lack of space for the task image file) or is 
not a fatal error, TKB creates the task image file anyway. Depending 
on the error condition, you may have to remove the cause of the error 
from the source file, reassemble the source file, and repeat the MTKB 
procedure. In some instances, the diagnostic condition is merely a 
warning and has no ill effect when the task runs. (For guidelines on 
typical error conditions, see Section 4.4.) 


When you create the task image from the single object module FILE.OBJ, 
TKB prints the following error message: 


TKB -- *DIAG*-2 Undefined symbols segment FILE 


READ 
WRITE 


The undefined symbols READ and WRITE are the entry points of the two 
routines defined by the object modules FILEA.OBJ and FILEB.OBJ. TKB 
searches the system object library to resolve global references left 
undefined in your input. Because TKB failed to find modules that 
defined these symbols, it reported the error condition. (This error 
message is generated from the MCR command.) You can eliminate the 
error condition by following the procedures described in the following 
section. 


4.1.2 Supplying Multiple Object Modules 
TKB accepts multiple object modules as input to the LINK command. At 
a DCL terminal, type the names of the object files, separated by 
commas, as shown: 

DCL>LINK FILE, FILEA,FILEB 


(any error messages appear) 
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The LINK command defaults to the file type OBJ for the three input 
files. The resulting task image file is named FILE.TSK. The LINK 
command defaults to the name of the first object file named to derive 
the name of the TSK file. 


From an MCR terminal, specify the names of the multiple object files, 
separated by commas, on the right side of the equal sign in your TKB 
command line, as shown: 


MCR>TKB FILE=FILE,FILEA, FILEB 
(any error messages appear) 
> 


TKB performs the same actions as those described in Section 4.1.1 for 
one object module from a DCL or MCR terminal. Only one of the object 
modules specified must have been assembled with a .END directive 
giving the starting address of the task. If one of the modules does 
not contain the starting address, TKB assigns the default transfer 
address of 1, which causes an error when you run the task. See 
Section 4.4. 


TKB can also accept as input a concatenated object module, which is 
merely a file containing multiple object modules. To create a 
concatenated file, use the DCL COPY command, as shown: 


DCL>COPY 

From? FILE.OBJ, FILEA,FILEB 
To? FILCON. OBJ 

> 


or 


DCL>COPY FILE.OBJ,FILEA,FILEB FILCON. OBJ 
> 


The response to the From? prompt lists the files to be concatenated. 
Note that you need specify the file type only on the first file 
listed. This type becomes the default file type for subsequent files. 
The COPY command automatically concatenates these files into a single 
output file. 


The single concatenated object file can then be the sole input to the 
LINK command, as shown in the following command line: 


DCL>LINK/TASK: FILE FILCON 
(any error messages appear) 
> 


This operation saves file-processing overhead for TKB. As a _ result, 
building a task from a concatenated file is possibly 40 percent faster 
than listing the object modules separately. 


Use the following PIP command line to create a concatenated file from 
an MCR terminal: 


MCR>PIP FILCON. OBJ=FILE.OBJ,FILEA, FILEB/ME 
> 


The right side of the command specifies the files to be concatenated. 
You need specify the file type (OBJ) only on the first file because 
PIP applies it as the default file type for subsequent names. 
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The designation /ME tells PIP to merge (concatenate) all the files 
into the one file specified on the left side of the equal sign. (When 
you supply multiple file specifications on the right side of the 
command line, PIP uses /ME as a default condition. The command line 
includes /ME merely to emphasize the concatenate, or merge, 
operation.) 


The single concatenated object file can then be the sole input to TKB, 
as in the following command line: 


MCR>TKB FILE=FILCON 
(any error messages appear) 
> 


This operation saves file-processing overhead for the TKB program and 
is faster than supplying the object modules separately. 


4.1.3 Using the Fast Task Builder 


Often you are performing repetitive, straightforward task-building 
functions where speed is preferable to versatility. In such 
circumstances, you should use the Fast Task Builder (FTB). From a DCL 
terminal, use the LINK command with the /FAST qualifier to specify the 
FTB. Here is an example: 


DCL>LINK/FAST/MAP FILE,FILEA, FILEB 
> 


To invoke the FTB from an MCR terminal, use the following command: 


MCROFTB FILE, FILE/-SP=FILE,FILEA,FILEB 
> 


FTB runs three to four times faster than TKB but is less versatile 
than TKB. For example, FTB does not create a global cross-reference 
listing or a symbol definition file. In addition, the FTB map has 
less information than the TKB map. 


4.2 TASK BUILDER DEFAULTS 


When you build a task image, TKB applies certain default conditions to 
your program, including the partition in which your task runs, the 
host system memory management characteristics, the task's 
checkpointability, and the number of logical units your task can 
access. If your program does not use the default conditions, the 
process of building a task becomes more complex. You can consult the 
RSX-11M/M-PLUS Task Builder Manual for the procedures to override the 
default conditions. 


TKB assigns your program to be run in the default partition, called 
GEN. If you are building a task to run in another partition, you can 
either supply the correct partition name at run time or rebuild the 
task and specify the correct partition name then. 
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TKB applies memory management characteristics depending on the system 
on which you build the task. If your system has memory management 
hardware, TKB allocates memory starting at virtual address 0 and 
assumes that the task will be relocated by memory management hardware. 
Therefore, the task can be run in any partition large enough to 
contain the image. If your system does not have memory management 
hardware, TKB assumes that the task runs at a fixed physical address 
that the system must supply. 


On RSX-11M systems, TKB assumes that the task is not checkpointable 
and does not use the floating-point processor. 


On RSX-11M-PLUS systems, TKB assumes’ that the task is not 
checkpointable; however, it does use the floating-point processor. 


TKB establishes the maximum number of logical units (six) the task can 
access and supplies the assignments for these logical units. The 
default assignments are: logical units 1 through 4 are assigned to 
the system device (SY:); unit 5 is the task-initiating terminal 
(TI:); and unit 6 is the console listing device (CL:). These 
defaults mean that the task can simultaneously refer to at most four 
files on the system device, one file on the task-initiating terminal, 
and one file on the system console listing device. 


4.3 GENERATING A MAP AND A GLOBAL CROSS-REFERENCE LISTING 


Before you run the task and correct simple errors, you can produce a 
memory allocation file (called a map) and a cross-reference listing of 
giscbal symbols. The map and global cross-reference file are useful in 
later stages of program development and for program documentation. 


4.3.1 Requesting a Map and a Global Cross-Reference Listing 


In most situations, you need a_= standard map and a global 
cross-reference listing for debugging a task. To create a map with a 
global cross-reference listing from a DCL terminal, type the following 
command line: 


DCL>LINK/CROSS_REFERENCE/NOWIDE/NOTASK FILE, FILEA,FILEB 
> 


The /NOTASK qualifier suppresses the creation of a task image file. 
You request a cross-reference listing with the /CROSS REFERENCE 
qualifier. The designation /NOWIDE reduces the width of the listing 
from 132 columns to 80 columns’ for display on a terminal. Since 
/CROSS REFERENCE implies a map, you do not have to specify the /MAP 
qualifier. 


If you wish to create both the task image file and the map with the 
cross-reference listing at the same time, use the following command 
line: 


DCL>LINK/CROSS/NOWIDE FILE,FILEA,FILEB 
> 


TKB creates both FILE.TSK and FILE.MAP. The map includes a 
cross-reference listing. 
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Here is the same procedure, as performed from an MCR terminal: 


MCR>TKB ,FILE/CR/-SP/-WI=FILE,FILEA,FILEB 
> 


The right side of the equal sign is the input object module (or 
concatenated object module or multiple object modules). The left side 
of the equal sign in the command line specifies the map file name, to 
which TKB appends the file type MAP. The comma preceding the map file 
name suppresses the creation of the task image file.1l 


To create a new version of the task image file when you request the 
map and global cross-reference listing, type the command as follows: 


MCR>TKB FILE,FILE/CR/-SP/-WI=FILE, FILEA,FILEB 
> 


TKB creates both files. 


The designation /CR tells TKB to generate a request for the CRF task 
to produce a global cross-reference listing. The designation /-WI 
reduces the width of the listing from 132 columns to 80 columns’ for 
display on a terminal. The CRF task executes the request from TKB and 
appends the global symbol cross-reference listing file to the end of 
the map file. The global cross-reference in the map listing is 
denoted by the title GLOBAL CROSS REFERENCE. 


NOTE 


If, after you request a global 
cross-reference listing, you discover 
that the map does not have one, the CRF 
task is either not installed on the 
system or still processing the reguest. 
Consult the system manager to have the 
CRF task installed. 


4.3.2 Examining the Map at the Terminal 


Use the DCL TYPE command, as described in Section 3.4, to examine the 
map at your terminal. Here is the command line: 


DCL>TYPE FILE.MAP 
(file appears on screen) 
> 


From an MCR terminal, use the following PIP command line, as described 
in Section 3.4, to examine the map at your terminal: 


MCR>PIP TI:=FILE.MAP 


(file appears on screen) 


1. The task image specification is null when a comma appears first in 
the command line. If you omit the comma, TKB treats the file name for 
the map as a task image and generates a syntax error because the 
designation /CR/-SP is illegal with a task image file. 


4-6 


BUILDING AND TESTING A TASK 


Use the control commands CTRL/S, CTRL/Q, and CTRL/O, summarized in 
Table 3-1, to control the terminal output. 


4.3.3 Requesting a Full Map 


The map file produced, as described in Section 4.3.1, is a short form 
of the map that contains most of the information needed for debugging 
tasks. To generate a full form of the map, use the following command 
line from a DCL terminal: 


DCL>LINK/LONG/MAP: FULL/CRO/SYSTEM_ LIBRARY DISPLAY/NOTASK FILE, FILEA,FILEB 
> 


The /LONG qualifier indicates that you want the LONG form of the map, 
and causes TKB to add a "File Contents" section to the map. The /LONG 
qualifier implies the /MAP qualifier, but /MAP is used here to give 
the map file for the name FULL.MAP so that you can tell apart the maps 
you have made for this demonstration session. The /CRO is’ the 
abbreviated form of the /CROSS_ REFERENCE qualifier. The 
/SYSTEM LIBRARY DISPLAY qualifier (usually abbreviated to /SYS) tells 
TKB to include system library contributions to the task in the file 
contents section of the map. (System symbols are also included in the 
global cross-reference listing.) 


To generate a full form of the map from an MCR terminal, specify the 
command line to TKB as follows: 


MCR>TKB ,FULL/-SP/-SH/MA/CR=FILE,FILEA,FILEB 
> 


The comma without a task image file name indicates you do not want TKB 
to build a task. The name FULL for the map file is used here to give 
that file the name FULL.MAP so that you can distinguish it from other 
maps you have created as part of these demonstrations. The 
designation /-SH indicates that you do not want the short form of the 
standard map. TKB therefore includes the file contents information in 
the map. The designation /MA tells TKB to include system library 
contributions to the task in the file contents section of the map. 
(System symbols are also included in the global cross-reference 
listing.) 


4.4 RUNNING THE TASK AND CORRECTING TYPICAL ERRORS 


You execute your_task by using the RUN command and the name of the 
task image file.1 For example: 


>RUN FILE 


Because the task FILE is not installed on the system, the RUN command 
searches your UFD on device SY: for a file named FILE.TSK. RUN 
installs it temporarily and runs it immediately. (The task will be 
automatically removed when the task exits.) 


1. Both MCR and DCL include a RUN command, each of which has many 
formats. The form shown in the example is perhaps the most widely 
used form for program development. This form, which is the same in 
MCR and DCL, runs a task from a task image file in your UFD. See the 
RSX-11M/M-PLUS MCR Operations Manual or the RSX-11M/M-PLUS Command 
Language Manual for more information on the functions of the RUN 
command, 
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To run task FILE, the Executive transfers control to the task 
Starting, or transfer, address. If your task encounters an error 
condition, the Executive must decide whether to abort the task. 


Errors that can cause the Executive to abort a task are either 
hardware related or software related. If the error is hardware 
related, such as a memory parity error or a load failure, the 
Executive begins aborting the task. In contrast, a synchronous system 
trap (SST) error condition, such as an illegal instruction, causes the 
Executive to attempt to transfer control to an SST routine. An SST 
routine is a routine within a task that services a particular type of 
SST condition. If your task defines a routine to service the type of 
trap, the Executive transfers control to it. If your task does not 
have the routine defined, the Executive aborts the task. 


Aborting a task forces an orderly termination of the task. Included 
in the termination is a request for the Task Termination and 
Notification (TKTN) to display a message on your’ terminal. The 
Program display includes the cause of the abort and a list of the task 
registers and Processor Status Word (PS). For example: 


14:16:26 Task "TT30 " terminated 
Odd address or other trap four 
RO=000000 
Ri=100103 
R2=147100 
R3=140130 
R4=000000 
R5=000000 
SP=001172 
PC=000003 
PS=170017 
> 


The information can help you ascertain the cause of the abort.1 If the 
cause of the error is hardware related, report the occurrence to your 
system manager, who can consult the error-logging data to find where 
the problem originated. If the cause of the error was an SST 
condition, you can use the data displayed by TKTN to find the problem. 


The value of the program counter (PC) (minus 2) shown in the display 
tells you the address of the instruction that was being executed when 
the error was encountered. In the example shown above, the PC is at 
an odd address (000003). By examining the task map, you can ascertain 
that the PC address is not within the task code. This condition 
demonstrates one of the more common error conditions. The main module 
NUMA source file FILE.MAC does not define a task transfer address. 
The .END directive in a source file, used to define the starting 
address of a task, does not have the address symbol of the first 
instruction. If you omit the starting address definition, TKB 
supplies a default transfer address of 1. When you run the task, it 
causes an odd address trap and terminates. (Note that the PC has been 
incremented to 000003 because it is pointing to the next instruction 
in the code.) Therefore, you should ensure that the source file 
defines a starting address and that the address is even (on a _ word 
boundary). 


To correct any errors in your task, you must edit the source file(s) 
concerned, reassemble the corrected file(s), and rebuild the task. 


1. The format of the information varies between RSX-11M and 
RSX-11M-PLUS. 
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For example: 


MCR>EDI FILE.MAC 
(00103 LINES READ IN] 


[PAGE 1] 
*L END 
. END ; TELL ASSEMBLER END OF CODE 


*c /D /D 8) START/ 
- END START 

*EX 

[EXIT] 


TELL ASSEMBLER END OF CODE 


™e 


>MAC FILE, FILE/-SP=FILE 

>TKB FILE,FILE/-SP=FILE,FILEA,FILEB 
>RUN FILE 

ABCABCABAB 

THE NUMBER OF A'S IS 0004 

> 


After you correct the errors and rebuild the task, you can run the 
task again. The task reads the line of text that you type, counts the 
number of As, displays the result, and exits. 


The typical errors made in programming result in an SST condition. 
The common conditions are either an odd address or a memory protection 
trap. Most of these errors occur when you use relative mode 
addressing instead of immediate mode. For example: 


MOV #BUF1,RO 
MOV OFFSET (RO) ,R1 


=e Ne 


The immediate mode reference #BUF1 moves the address of BUF1 into 
register 0. If you omit the number sign (#), however, you incorrectly 
specify relative mode addressing, as follows: 


MOV BUF1,RO 
MOV OFFSET (RO) ,R1 


This instruction moves the contents of BUFl and not the address of 
BUF1 into RO. The subsequent indexed mode reference generates either 
an odd address or memory protection trap. (Your task is attempting 
either to illegally reference an odd address or to reference a 
location outside task memory). This type of error occurs often when 
you are using system directives that require parameters as immediate 
mode references, and when you omit the number sign from a parameter 
that makes the reference relative. 


4.5 GUIDE TO FURTHER READING 


The sections or chapters in the following documents contain additional 
information on the subjects described in this chapter. 


Document 
RSX-11M/M-PLUS Command Language Manual 


Section 6.4, Linking the Task 
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Document 
RSX-11M/M-PLUS Task Builder Manual 


Section 1.1, The Task Command Line 
Section 10.1, Switches 

Section 11.1, Options 

Appendix G, The Fast Task Builder (FTB) 
Appendix H, Error Messages 


RSX-11M/M-PLUS Utilities Manual 


Chapter 3, Peripheral Interchange Program (PIP) 
Appendix B, The Cross-Reference Processor (CRF) 


CHAPTER 5 


USING DEBUGGING AIDS 


This chapter introduces three debugging aids that are helpful in the 
program development process: the On-Line Debugging Tool, the 
Postmortem Dump, and the snapshot dump. 


5.1 THE ON-LINE DEBUGGING TOOL 


The On-Line Debugging Tool (ODT) is a special code that you include in 
your task image to assist you during debugging. ODT gives you 
interactive control of task execution, and allows you _ to set 
breakpoints and to examine and change data and instructions within the 
memory-resident task. The ODT module is linked into your task image, 
thereby increasing the size of the task image. Therefore, you remove 
ODT from your task when you finish debugging by rebuilding the task 
and omitting the ODT module. 


ODT commands differ from commands in other utility programs. Most 
programs have multiple-character commands that require a line 
terminator before they are executed. ODT commands, however, are 
single characters and require no iine terminator. That is, ODT 
interprets input on a character-per-character basis rather than on a 
line-by-line basis. Therefore, aS soon as you type a character that 
ODT recognizes aS a command, ODT interprets it and performs the 
specified function. This difference in commands means that you must 
be careful when you are debugging your task with ODT. 


5.1.1 Including ODT in a Task 


The /DEBUG qualifier to the LINK command is used to include ODT in a 
task. Here is an example: 


DCL>LINK/DEBUG/TASK: BUG/MAP: BUG/CROSS_REFERENCE FILE, FILEA, FILEB 
> 


The /DEBUG qualifier specifies that you want to include ODT in the 
task. The /TASK:BUG qualifier specifies that you want the task image 
file to be named BUG.TSK. The /MAP:BUG qualifier specifies that you 
want the map to be named BUG.MAP. In this way, you can tell the 
difference between the versions of the task-built file with ODT and 
without. The Task Builder (TKB) accesses the file LB:[1,1]ODT.OBJ and 
links it into the task. The /CROSS REFERENCE qualifier implies a /MAP 
qualifier. An accurate map of the task is necessary for use with ODT. 
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To include ODT in a task from an MCR terminal, type a command line 
similar to the following: 


MCR>TKB BUG/DA, BUG/CR=FILE,FILEA,FILEB 
> 


The designation /DA accompanying the task image file specification 
tells TKB to include ODT. TKB accesses the file ODT.OBJ in UFD [1,1] 
on the library device and links it into the task BUG. You should 
request a map of the task because an accurate map is necessary for use 
with ODT, 


5.1.2 Preparing to Use ODT 


Before you run a task containing ODT, ensure that accurate listings of 
the assembled source files are available. These listings show the 
offsets into the modules in your task. The map of the task and_ the 
assembled source listings provide the data you need to set breakpoints 
and examine locations within the task. 


5.1.3 Setting up the Task 


When you run a task containing ODT 
itself (and the task it controls), 


following lines show the sequence: 


ODT gains control, identifies 
ints its command prompt. The 


>RUN BUG 
ODT: TT30 


The notation TT306 is the name that the system dispatcher assigned to 
the task. Such a name consists of the letters TT followed by the unit 
number of the terminal that requested the task. (The task shown here 
was run from terminal number 30 (8).) 


The underline character (_) is ODT's prompt. It indicates that ODT is 
ready to accept commands. 


5.1.4 Relocation Registers 


To access locations within the task, you should establish one or more 
relocation registers. This set of eight registers, numbered $RO 
through $R7, allows you to specify locations within the task in terms 
of offsets from the start of modules in the task image. 


To establish the proper addressing using offsets, you must first 
consult the location information in the task map. On the map 
printout, the portion titled Memory allocation synopsis contains the 
location information for each program section and for each 
contribution to the program sections from different modules. A sample 
of the relevant portion of the map for the program BUG is shown in 
Example 5-1. 


USING DEBUGGING AIDS 


Example 5-1 Memory Allocation Synopsis from Task BUG Map 


Memory allocation synorsis! 


Section Title Ident File 
+ BLK.¢CRWsIsLCLsREL» CON) 0012062 000340 00224. 
061202 000122 00082. NUMA o1 FILCON.OBJ#1 
001324 000110 00072. TTREAD 01 FILCON.OBJ#1 
001434 000106 00070. TTWRIT 01 FILCON.OBJ?1 
DATA $C(RWrDsLCL»REL»CON) 001542 000164 00118. 
001542 000156 00110. NUMA o1 FILCON.OBJ#1 
601726 000004 00004. TTREAD 01 FILCON.OBJ51 
901724 000004 00004, TTWRIT 01 FILCON.OBJ#1 
S¢SODT i (RWs IT eGBL REL sOVR) 001720 005454 02988. 


001730 005654 02986. ODTRSX M046 ODT.OBJ3121 


The location information for a program section is the octal starting 
address of the program section and its extent in bytes (both octal and 
decimal values). For example, for the blank program section, the 
starting location is 1202 (8) and the extent is 340 (8), or 224 (10), 
bytes. Under the program section location information are the octal 
Starting addresses and extents in bytes for the contributions from 
each object module. For example, the contribution from TTREAD in the 
blank program section starts at location 1324 and extends for 110 (8), 
or 72 (10), bytes. 


The following example shows how to place the starting addresses of the 
modules in relocation registers: 


_1202;0R 
—1324;1R 
_1434;2R 
~1542;3R 
71720; 4R 
71724; 5R 


The R commands place the addresses in relocation registers 0 through 
5. (The addresses are octal; ODT accepts only octal numbers.) As 
soon aS you type the R in the command line, ODT generates line feed 
and carriage return operations and prints another prompt. This action 
indicates that ODT has executed the command as soon as it was typed. 
Therefore, before typing the R (or any command), ensure that the 
command line is correct. 


If you notice a typographical error in the line before you type the 
command itself, simply type either CTRL/U, the number 8 or 9, or the 
DELETE key, as shown in the following example: 


_1272;08? 


ODT considers the decimal number 8 an illegal character. It discards 
the input line, displays a question mark (?) to signal an error, and 
prints the prompt on a new line. You must retype the entire line. If 
you do enter an incorrect address in the relocation register, simply 
retype the command, as follows: 


_1272;0R 
~1202;0R 


ODT stores the most recently entered value in the register. 
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To access a location within a task most conveniently, you must create 
an address made up of the values stored in the relocation register and 
a value showing the distance of the location from the relocation 
register value. 


The relocation register provides the base address of a module; the 
location counter value supplies an offset to the location within the 
program section for the module. The command 1202;0R places the 
starting address of the NUMA contribution to the blank program section 
in relocation register 0. Location counter value 20 in. the assembly 
listing for NUMA is 20 bytes from the start of the address in 
relocation register 0. You use the two values to form the address of 
the location. The address is formed by typing the number of the 
relocation register, a comma (,), and the octal offset value. For 
example: 


0,20 


ODT adds the base value in relocation register 0 (1202 in this case) 
and the offset typed after the comma (20). This creates an effective 
address of 1222 (8). You use this syntax with various ODT commands to 
access locations within the task address space. 


Example 5-2 shows a portion of the assembly listing for the blank 
program section in the module NUMA. 


Example 5-2 Portion of Assembly Listing for NUMA 


Syste ee 2 


NUWA COUNT NUMBER OF 4’S MACRO M1200 8-AUG-81 12339 PAGE 3 
ROUTINE TO COUNT A’S 
66 *SBTTL ROUTINE TO COUNT A‘S 
67 000000 »PSECT 
&& 260000 STARTS 
69 000000 012700 MoV SBUF1>RO 3 LOAD BUFFER ADDR 
79 000004 012701 MoV #SIZeRi * LOAD BUFFER SIZE 
71 000010 004767 CALL READ > READ FROM TTY 
72 000014 005702 TST R2 3 ANY CHARS IN BUFFER? 
73 060014 001424 BEQ ENE ' IF NGNE+ FINISH UP 
74 000020 005001 CLR Rl ¢ INIT # OF A’S COUNTER 
75 000022 010247 MOV R2» NUNC * SAVE # OF CHARS TYPED 
76 000026 1083 
77 000026 122067 CNPB (RO) t2A ' IS CHAR = A? 
78 000032 001001 BNE 20% ¢ IF NO» BET NEXT CHAR 
7% 000034 005201 INC R1 § COUNT AN A 
80 000036 2083 
81 0000346 005302 DEC R2 * ONE LESS CHAR 
82 000040 001372 BNE 10$ — 3 IF MORE» COMPARE NEXT 


5.1.5 Examining Locations 


To examine words within a module, type the address followed by the 
Slash (/) character, as follows: 


_0,20/005001 


The Slash character causes ODT to open the designated location as a 
word and display its contents. 
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To close the currently open location, type either the RETURN key or 
the LINE FEED key. The RETURN key closes the location, as shown in 
the following example: 


_0,20/005001 


ODT closes the location and prints its prompt on a new line. 


Once you have opened a location, typing the LINE FEED key enables you 
to examine successive words in the task image. The following example 
shows the procedure: 


_0,32/001001 
0,000034 /005201 @& 


In response to the LINE FEED key, ODT closes the current location, 
opens the next sequential location in the task image, and displays the 
address of the location, a space, the slash character, and the 
contents of the location. The slash character signals that the 
location is open as a word. 


NOTE 


You can change the contents of the 
currently open location to n by typing 
the octal number n before typing the 
RETURN or LINE FEED key. See Section 
5.1.7. 


To examine bytes within a task instead of words, type the address 
followed by the backslash (\) character, as follows: 


_0,32\001 


The backslash character causes ODT to open the designated location as 
a byte and display its contents. You can examine successive bytes by 
typing the LINE FEED key, after which ODT closes the currently open 
byte location, opens the next sequential byte location, and displays 
its contents. For example: 


_32\001 
0,000033 \002 & 


The backslash character preceding the contents signals that the 
location is open as a byte. 


Before you proceed in the debugging session, you should verify the 
relocation register values by examining a location in each module and 
comparing its contents with the values shown in the assembly listing. 
The following sequence shows the procedure: 


_1,66/002403 & 
~2,72/000207 
~3,121\124 

~4,0/000000 
75,0/000000 


As you examine each location, compare the contents ODT displays with 
the assembly listing. If the values do not match, either you have an 
incorrect listing or the relocation register value is wrong. 
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5.1.6 Setting Breakpoints Within the Task 


To allow you to stop (or break) task execution, ODT provides eight 
registers called breakpoint registers. These registers, numbered $BO0 
through $B7, let you specify locations of instructions at which 
execution should stop. 


To establish breakpoints in the task, specify the location of the 
instruction with the B command in the format a;nB, as in the following 
example: 


_0,10;0B 
~1,74;1B 


The command places the designated addresses in breakpoint registers 0 
and l. 


NOTE 


In specifying the address of an 
instruction, ensure that the location is 
the first word of the instruction. 


AS soon as you type the B in the command line, ODT generates the 
carriage return and line feed operations and prints a prompt. 
(Changing a breakpoint register is the same as changing a_ relocation 
register; simply retype the command line and give the altered 
contents.) 


After setting up the breakpoint registers, you can issue the G (Go) 
command to begin task execution. For example: 


_G 
0B:0,000010 


When you type the G command, ODT Swaps a BPT instruction into each 
breakpoint location.! opDT passes control to the starting address of 
the task. The task executes until it reaches a BPT instruction, at 
which point ODT regains control. When ODT regains control, the task 
has not yet executed the instruction at the location where the 
breakpoint is set. ODT swaps the instructions back into the locations 
at which breakpoints are set, and prints a message giving: 


e The breakpoint register designation 
@ The relocation address at which execution stopped 


In the example above, the message shows breakpoint register 0 and its 
contents (offset 10 from the base address in relocation register 0). 


1. The eight breakpoint instruction registers, with register names $10 
through $I7, contain the actual instructions during task execution. 
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5.1.7 Changing the Contents of Locations with ODT 


When execution stops at a breakpoint, you can examine and change data 
within the task image address space. When execution stops at a 
breakpoint location, the task's general registers are stored in ODT 
locations accessed by the names $0 through $7. The following sequence 
shows a way to display general registers 0, 1, and 2: 


_$0/ 001543 
$1 /000120 
$2 /135600 © 


The slash (/) character opens the general register as a word location 
and prints its contents. Typing the LINE FEED key closes the current 
location and opens the next sequential location. 


To change data, simply type a new value while the current location is 
open. The following sequence shows a way you can change register 2: 


_$2/ 135600 100 
$3 /140130 


While the location (register 2) is open, you can type the new value to 
replace the current contents. ODT writes the new value 100 (8) into 
the currently open location before closing it and opening the next 
sequential location. 


Any locations within the task can be examined and changed. The 
following sequence shows a way to open a location as a byte and change 
its contents: 


_3,0\101 102 @ 
~3,0\102 101 


The backslash (\) character opens the specified address as a byte 
location. The new value 102 (8) is written to the open location as a 
byte value. Typing the RETURN key closes the location. The next 
command line examines offset 0 to verify that it contains 102 (8) and 
then changes the contents back to 101. 


After you examine and change locations, resume execution with the P 
(Proceed) command, as follows: 


__PABCABCABAB 
1B:1,000074 


The P command causes ODT to swap in the BPT instructions, restore the 
task general registers, and continue with the instruction at which the 
break occurred. 


NOTE 


ODT does not supply a carriage return 
and line feed after you type the P. 
Therefore, the data that you type in 
response to the READ routine will follow 
the P on the same line. 
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Execution stops at the location contained in breakpoint register l. 


The G command is used to transfer control to another address. and 
continue execution. For example: 


_1,76G 


ODT transfers control to offset 76 and continues execution there. 
This command purposely tranfers control to the error routine to show 
what occurs when an error is encountered. See Section 5.1.8. 


5.1.8 Error Conditions and Terminating Task Execution 


If the task generates an error condition, the Executive handles the 
processing as a synchronous system trap (SST). Control is passed to 
ODT, which prints a message similar to the following one: 


I0:2,000000 


This message gives a code describing the reasons for the trap and 
tells the address following the location that generated the trap. In 
the message above, I0 means the IOT instruction. If you can discover 
the cause of the trap, make the appropriate changes in the task and 
proceed. If you cannot isolate the cause of the trap, you should exit 


To help ascertain the cause of the trap, you can examine the task 
registers and stack before you start a new debugging session. Use the 
register name -- the dollar sign ($) followed by the register number 
-- to access the task registers as described in Section 5.1.7. To 
examine the stack, examine register 6 (the stack pointer) and use the 
at sign (@) to open the location pointed to by the stack pointer. for 
example: 


_$6/001200 @ 
001200 / 001216 


The slash (/) character opens the stack pointer as a word and displays 
the address of the top of the stack. The at sign character (@) takes 
the contents of the currently open location (that is, the stack 
pointer) as the address of the next location to be opened, opens it, 
and displays its contents, which is the top word on the stack. 


To examine the slack, type the LINE FEED key to open and display each 
Successive word on the stack. You can ascertain the highest address 
the stack can have by consulting the line labeled Stack limits in the 
task attributes section of the map. The line gives four numbers: the 
low address of the stack area, the high address of the stack area, and 
the octal and decimal extent of the stack area. The high address 
tells you the last available location (that is, the bottom) of the 
stack. After you have examined the highest address, you have looked 
at all the items on the stack and can type the RETURN key to close the 
last available location. 


To exit from the task by means of ODT, use the X command as follows: 


Xx 


ODT performs the exit task directive and returns control to the 
Executive. 
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5.2 POSTMORTEM DUMP 


Another debugging aid is the Postmortem Dump (PMD). It requires no 
special code in your program. The examples show how to enable PMD for 
your task using either the /POSTMORTEM qualifier or the /PM qualifier. 
These qualifiers set a bit in the task flag word that causes a PMD 
whenever the task exits unexpectedly. 


To enable PMD from a DCL terminal, type the following command line: 


DCL>LINK/MAP/POSTMORTEM FILE, FILEA, FILEB 
> 


From an MCR terminal, use the following command line: 


MCR>TKB FILE/PM,FILE/-SP=FILE,FILEA,FILEB 
> 


The /POSTMORTEM qualifier in the LINK command is the equivalent of the 
/PM in the TKB command after the task image file name. In either 
case, TKB is instructed to set a bit in the task flag word.! (You can 
tell whether a task includes PMD by inspecting the task attributes 
section of the map. A line item called Task attributes will have the 
designation PM.) When PMD is in effect for a task, the occurrence of 
an error that generates a synchronous system trap (SST) causes’ the 
Executive to handle the termination of your task in a special 
manner.2 Instead of simply aborting the task, the Executive generates 
a request for PMD to create a formatted disk file showing the task 
image context. When a task generates a synchronous system trap, the 
Executive initiates the normal task termination procedure (the 
printing of an error message and general register contents at the 
terminal) and additionally generates the request for PMD. To inform 
you that a dump is in effect, the Executive causes the following 
message to appear at the terminal: 


Post mortem dump will be generated 


PMD receives the request, creates a file in UFD [1,4] on tthe library 
device, and generates a request to the spooler to print the file. The 
file has the name of the task and a type of PMD. The print spooler 
automatically deletes a file with the file type PMD after it is 
printed. 


5.3 THE SNAPSHOT DUMP 


The snapshot dump capability is a subset of the Postmortem Dump task 
but requires special code in the task. Whereas PMD generates a dump 
of an entire task, the snapshot dump can produce a dump of only a 
portion of the task. Also, PMD generates a dump only when the task 
terminates abnormally, but the snapshot code can produce a dump at any 
place in the task execution. 


1. You are not limited to specify PMD at the time you build the task. 
Postmortem dumps can also be specified as part of the RUN, INSTALL, 
and ABORT commands. See the RSX-11M/M-PLUS Command Language Manual or 
the RSX-11M/M-PLUS MCR Operations Manual for more information. 


2. This discussion assumes that the task does not handle synchronous 
system traps through the SVTKS$ directive and specially coded routines. 
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You include the necessary snapshot code in the task by editing the 
source file and inserting the snapshot macro calls where you want to 
produce a dump.1 After you reassemble the modules containing the 
Snapshot calls, rebuild the task and substitute the reassembled 
modules. When you use snapshot macro calls, you do not need any 
special switches or options for TKB. 


When you run the task and that section containing the special code is 
executed, a snapshot dump is taken. The special code generates a 
request for the PMD task. (No special messages are printed at the 
terminal.) To hold the dump, PMD creates a file with the name of the 
task and a file type of PMD in the UFD that is the same as the UIC 
under which the task is running. PMD then generates a request for the 
spooling task to print and delete the file. 


5.4 GUIDE TO FURTHER READING 


The sections or chapters in the following documents contain additional 
information on the subjects described in this chapter. 


Document 
RSX-11M/M-PLUS Task Builder Manual 


Appendix D, Memory Dumps 
Section D.1, Postmortem Dumps 
Section D.2, Snapshot Dumps 


IAS/RSX-11 ODT Reference Manual 


Section 1.2, Linking ODT with a User Program 

Section 1.4, Returning Control to the Host System 

Section 2.2.1, Absolute and Relative Addressing 

Chapter 3, Controlling Program Execution 

Section 3.1, Setting and Removing Breakpoints 

Chapter 4, Displaying and Altering the Contents of Locations 
Section 4.10, Using Different Output Modes 

Section 5.2.1, Relocation Registers 

Section 7.1, Calculating Relocatable Addresses 


1. The snapshot macro calls the PMD task as described in an appendix 
of the RSX-11M/M-PLUS Task Builder Manual. 
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CREATING AND USING PROGRAM LIBRARIES 


This chapter describes the procedures to create and maintain a library 
of macro source statements and a library of object module subroutines. 
It also shows how to include in your task image the macro call 
definitions and the object subroutines from user-created libraries. 


The decision about whether to implement specific code as a macro call 
or aS an object module subroutine is left to the designer. In 
general, the difference between implementations is a tradeoff of 
assembly time versus linking time and, secondarily, convenience versus 
size. Each time your source file invokes a specific macro call, the 
assembler must include the macro expansion in the object module. 
However, when your program calls an external subroutine, the 
resolution of the call is done during linking. Moreover, using the 
Macro call to generate in-line code is convenient, but each invocation 
of the call increases the size of the resulting task image. However, 
if your program calls a specific external subroutine more than once, 
the subsequent invocations do not include that code in the task. 


6.1 CREATING AND USING A MACRO SOURCE LIBRARY 


The Librarian Utility Program (LBR) creates and maintains library 
files that can contain macro definitions, object modules, or other 
elements. DCL users can invoke LBR_ functions through the LIBRARY 
command. MCR users can invoke LBR functions through the LBR command. 
This section discusses creating a library file of macro definitions. 
Such a file has the default type MLB and contains only macro 
definitions. 


6.1.1 Creating the Macro Library 


Here is how to create a macro library from one input file of source 
definitions using the DCL LIBRARY/CREATE command: 


DCL>LIBRARY/CREATE: (BLOCKS: 25,MODULES: 128) /MACRO 
Library? USRMAC 

Module(s)? USRMAC 

> 


or 


DCL>LIBRARY/CREATE: (BLOCKS: 25,MODULES:128) /MACRO USRMAC USRMAC 
> 


The /CREATE qualifier identifies the LBR function you want to invoke. 
The arguments to /CREATE specify features of the library you are 
creating. Because there is more than one argument, they are enclosed 
in parentheses and separated by commas. The argument BLOCKS:25 gives 
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the length in blocks for the library file. (DCL uses the decimal 
value automatically for all LIBRARY command arguments.) If you omit 
this argument, LBR creates a file 100 blocks long by default. The 
argument MODULES:128 indicates the number of module name table entries 
to allocate for this library. (Each macro definition in the library 
requires an entry in the module name table.) The /MACRO qualifier 
identifies the type of library you wish to create. The default type 
is /OBJECT (to create an object module library). 


The Library? prompt requests that you name the library to be created. 
For macro libraries, the default file type is MLB. The Modules? 
prompt requests you to name the file or files containing the macro 
definitions. The default file type for this parameter is MAC. (If 
you do not name a file here, LBR creates an empty file.) 


There is further discussion of how LBR creates a library included in 
the MCR command description. Here is the MCR command line to create a 
macro library: 


MCR>LBR USRMAC/CR:25.::128. :MAC=USRMAC 
> 


The designation /CR tells LBR to create a library file. LBR creates 
the library file USRMAC.MLB. For input to the library file, LBR uses 


the file or files specified to the right of the equal sign. In 
Example 6-1, the input file is USRMAC.MAC, 


Example 6-1 MACRO-11 Library Source Definitions 


SAVE ~ STORES REGISTER ON STACK 


or ae ee 


»MACRO SAVE>REG # PUSH REG ONTO STACK 
MOV REGr-(SP) 
»ENDM 


RESTOR - POPS REGISTER VALUE OFF STACK 


ap a> owe 


+MACRO RESTOR: REG 

MOV (SP) +4+/REG 3 POP REG OFF STACK 
+ENDM 

-ENB 


Following the designation /CR in the command line are parameters, 
separated’ “by colons, (hat-LBe Uses: to. crcate the litrary 1 The. first 
parameter, 25 (decimal), gives the length in blocks for the library 
file. If you omit this parameter, LBR uses 100 (decimal) blocks as 
the default length. When creating the library file, you can allow for 
some future additions to the library by making the size larger than 
necessary. (LBR will expand a library file as needed if you add 
modules that will cause the file to exceed its original size. 
However, the library will no longer be contiguous.) The second 
Parameter is blank because it applies only to object libraries. The 
third parameter, 128 (decimal), is the number of module name table 
entries to allocate for this library. (An entry in the module name 
table is required for each macro definition.) Following the third 
parameter is the type of library to create (MAC for macro definition). 


1. The numeric parameters are followed by decimal points to force LBR 
to interpret them as decimal numbers. If you omit the decimal points, 
LBR treats the numbers as octal. 
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You must specify this parameter because the default is an object 
library. 


In creating the macro library, LBR allocates the requested amount of 
contiguous file space. If sufficient contiguous space is not 
available, LBR generates the OPEN FAILURE error and terminates. To 
have the library created, you must either free up some space on the 
volume or try a smaller library size. 


When the library file is created, LBR attempts to insert into the 
library the macro definitions from the input file. LBR searches the 
input file for .MACRO directives and .ENDM directives. If the macro 
definitions are nested, only the outermost directives are directly 
callable from the library. From each macro definition, LBR extracts 
the name and creates an entry in the module name tabie. The entry in 
the module name table is the means by which the assembler finds the 
associated macro definition in the library. Any code or comments 
outside the directives are discarded and all trailing blank and _ tab 
characters, blank lines, and comments are eliminated from the macro 
text itself. (This action, called squeezing, conserves memory for the 
assembler and reduces the space required to hold the macro 
definitions.) Errors occurring during the insertion of definitions 
usually indicate improper definitions, such as a missing .ENDM 
directive. 


6.1.2 Using the Macro Definitions from the Library 


Once the macro definitions are in the library, you need perform only 
three actions to have the assembler include the macro expansions in 
your code. 


1. Include the name of the macro in a .MCALL directive in your 
program source file. 


2. Invoke the macro call within the source file. 


3. Specify the name of the library file in the command line to 
the assembler. 


Thus, to invoke the two macro library definitions SAVE and RESTOR in 
your program, precede the macro calls themselves with a statement such 
as the following: 


-MCALL SAVE,RESTOR ; CALL DEFINITIONS FROM USRMAC 
This statement should preferably occur at the start of the source 
file. When you assemble a source file that refers to a library file, 
you must name both files in your DCL MACRO command line. Here is an 
example: 

DCL>MACRO USRMAC/LIBRARY, USRTST/LIST 
The name of the macro library can appear anywhere but last in the list 
of input files and must be marked with the /LIBRARY qualifier. The 
next file named is the first source file. 


There is further discussion of how LBR creates a library. Use the 
following MCR command line to include a library in an assembly: 


MCR>MAC USRTST,USRTST/-SP=USRMAC/ML, USRTST 
> 


To the right of the equal sign in the command line, specify the name 
of the macro library and the designation /ML. The comma separates the 
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macro library file name and the source file name. The designation /ML 
indicates to the assembler that the file is a macro library. The name 
of the macro library must precede the source file that refers to the 
macro definitions. 


NOTE 


If the library specification follows the 
source file name in the command and the 
corresponding definitions are not in the 
system macro library RSXMAC, MACRO-11 
does not recognize the library file and 
generates assembly errors in the lines 
that contain calls to library 
definitions. 


To process the macro calls in the source file, the assembler uses the 
names given in the .MCALL directive to generate symbols for the macro 
symbol table.! To expand the macro calls not defined in the source 
file, the assembler searches the library you specified before it 
searches the system default macro library. MACRO-11 does not search 
the system macro library for definitions that are found in the user 
library file. 


6.2 CREATING AND USING AN OBJECT MODULE LIBRARY 


LBR may be used to create a library file containing object modules. 
Such a file has the file type OLB (object library) as a default and 
can contain only object modules. 


6.2.1 Creating the Object Module Library 


To create an object module library, you must have a file or files that 
contain the object modules to be inserted into the library. The 
following command creates the object library and inserts the modules 
FILEA.OBJ and FILEB.OBJ. Here is the DCL command to create an object 
module library consisting of the object modules in FILEA.OBJ and 
FILEB.OBJ: 


DCL>LIBRARY/CREATE: (BLOCKS: 25,GLOBALS:128,MODULES: 64) /OBJECT 
Library? USROBJ 

Module(s)? FILRA  FTTER 

> 


or 


DCL>LIBR/CRE: (BLO: 25,GLOB:128,MOD:64) /OBJ USROBJ FILEA,FILEB 
> 


1. If you omit the name of the macro call from the .MCALL directive, 
the assembler cannot recognize the call itself in the code. (A 
corresponding entry is not in its macro symbol table.) It treats an 
unrecognized macro call as an implicit .WORD directive. If the macro 
name is not a valid symbol, its usage is flagged as an undefined 
reference by TKB. 
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The /OBJECT qualifier is not required because it is the default, but 
it is a good idea to include it. The default file type for an object 
module library is OLB. The default file type for the object module 
files is OBJ. The arguments to /CREATE are the same as those used in 
creating a macro library with the addition of the GLOBALS argument, 
which applies to object libraries only. The GLOBALS argument 
specifies the number of entry point table slots to reserve. (An entry 
point is any global symbol in a module by which your program refers to 
the associated module.) If you do not supply a value, LBR defaults’ to 
GLOBALS: 512. If you supply a value of 0, you can maintain modules 
with duplicate entry points in the same library. The names of the 
modules must still be unique. When building a library with GLOBALS:0, 
you must specify the correct module namesS to TKB when you build your 
task, See Section 6.2.2. A good estimate for the number of GLOBALS 
is twice the number of modules the library will contain. The value 
should be a multiple of 64. If not, LBR raises the number to the next 
multiple of 64. Again, all these numbers are automatically decimal 
numbers in DCL. 


Here is the MCR command line: 


MCR>LBR USROBJ/CR:25.:128.:64.=FILEA,FILEB 
> 


There is further discussion of how LBR creates an object module 
library in the MCR command description. 


The designation /CR tells LBR to create a library file. LBR uses’ the 
name preceding /CR as the name of the library and applies the default 
file type OLB. Following /CR in the command line are parameters, 
separated by colons, used in creating the file. 


The first parameter, 25 (10), gives the size in blocks at which to 
create the library file. If you omit the parameter, LBR supplies 100 
(10) blocks as the default size. When creating the library, you can 
‘allow for future additions by making the size larger than necessary. 
(LBR will expand a library file as needed if you add modules that will 
cause the file to exceed its original size. However, the library will 
no longer be contiguous.) 


The second parameter, 128 (10), in the command gives the number of 
entry point table slots to reserve.2 A good estimate for the number 
of entry points is twice the number of modules the library will 
contain (that -is, two entry points per module). If you omit this 
parameter, LBR supplies 512 (10) as the default number. If the value 
you supply is not an integral multiple of 64 (10), LBR raises the 
number to the next highest multiple of 64 (10). 


The third parameter, 64 (10), is the number of module name _ table 
entries to create for the library. (The module name is the means by 
which LBR refers to the module code in the library.) If you omit this 
Parameter from the command line, LBR supplies 256 (10) as the default 
number. If the value you specify is not an integral multiple of 64 
(10}, LBR raises the number to the next highest multiple of 64 (10). 


s 


1. The numeric parameters are followed by decimal points to force LBR 
to interpret them as decimal numbers. If you omit the decimal points, 
LBR treats the numbers as octal. 


2. LBR allows you to build an object library having zero entry points. 
This feature allows you to maintain modules with duplicate entry 
points in the same library. (The names of the modules must still be 
unique.) When using such a library, you must specify the correct 
module name(s) to TKB when you build your task. See Section 6.2.2. 
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The last parameter (omitted from the command line above) specifies the 
type of library to build. LBR supplies OBJ as the default type. 


In creating the object library file, LBR allocates the requested 
amount of contiguous space. You can estimate the number of contiguous 
blocks that LBR requires by using PIP. Request a directory listing of 
all the files to be inserted in the library and use the total number 
of blocks PIP calculates. If sufficient contiguous space is not 
available, LBR generates the OPEN FAILURE error and terminates. To 
have the library created, you must either free up some space on the 
volume or try to build a smaller object library. 


When the object library is created, LBR attempts to insert into the 
library the object modules from the input file(s). It arranges the 
entries in the module name table in alphabetical order by module name. 
The module name that LBR uses is the one you specified in the .TITLE 
directive when you assembled the object module. The module names and 
entry points must be unique.l LBR finds the global symbols in each 
object module and enters them in the entry point table. If LBR finds 
a module name or an entry point that duplicates one already used, it 
prints an error message and stops processing. 


If LBR finds an error, it does not insert any modules in the library 
from the file containing the error. You must eliminate the error 
condition and insert the modules from the corrected file again. If 
LBR does not find any errors, it enters all the modules in the 
library. To ascertain what modules were inserted, obtain a listing of 
the library as described in Section 6.3.3. 


6.2.2 Using the Object Modules from the Library 


When the object modules are in the library, you need perform only two 
actions to have TKB include the routines in your task. 


1. Include the CALL x statement in the calling module (where x 
is an entry point to the called module). (It is assumed that 
the called module has a global statement to define the entry 
point.)< 


2. Specify the name of the library file and the names of the 
called modules in the command line to TKB. 


Thus, to invoke subroutines from the library, ensure that the CALL 
statements are in your program. 


1. If you suppress including entry points in the library entry point 
table, LBR allows you to insert, in the library, object modules having 
duplicate entry points. This feature enables you to maintain slightly 
different modules of the same general type in the same library. You 
select the correct module by specifying the unique module name to TKB 
when you build your task. See Section 6.2.2. 


2. CALL is a macro statement that is a permanent symbol in the 


MACRO-11 Assembler. It standardizes subroutine calling conventions. 
CALL x translates to JSR PC,x (where x is the subroutine entry point). 
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When you build a task, use a DCL LINK command line similar to the 
following: 


DCL>LINK/TASK: SUPLIB/MAP: SUPLIB 
File(s)? FILE,USROBJ/INCLUDE: (TTREAD, TTWRIT) 
> 


or 


DLC>LINK/TA:SUPLIB/MAP:SUPLIB FILE, USROBJ/INC: (TTREAD, TTWRIT) 
> 


By including filespecs as arguments to the /TASK and /MAP qualifiers, 
you cause the outfiles from the LINK command to be named SUPLIB.TSK 
and SUPLIB.MAP, respectively. The /INCLUDE qualifier identifies the 
file USROBJ.OBJ as an object library. The names appearing in 
parentheses, after /INCLUDE, are the names of the modules to be 
extracted from the library and placed in the task. (Remember that 
these module names are derived from the names given in the .TITLE 
directive in the MACRO source files, and not from the file from which 
these modules were assembled.) 


This method of specifying an object library search is more direct and 
faster than the method described in Section 6.2.3. If you are using a 
large library, TKB need only search the module name table for those 
object modules you specify. The disadvantage is that you have the 
responsibility to specify the names of all the modules that your’ task 
requires. If, however, you are using a library with zero entry 
points, the /INCLUDE qualifier is the only method of telling TKB which 
modules to include from that library. 


The following command line is the MCR equivalent for including 
specific object modules from a library in your task: 


MCR>TKB SUPLIB, SUPLIB/-SP=FILE, USROBJ/LB:TTREAD: TTWRIT 
> 


The designation /LB after a name in the command line indicates to TKB 
that the file is an object library. TKB accesses the file USROBJ.OLB 
in the UFD that is the same as the current UIC. The names appearing 
after /LB in the command line are the names of the modules to be 
extracted from the library and placed in the task. TKB searches’ the 
module name table of the library for these modules. (Remember that 
these module names are derived from the name given in the .TITLE 
directive, and not from the file names from which the modules were 
created.) 


Note that the module names in the command line are preceded by colons, 
which are necessary to distinguish the names as library module names. 
Placing a comma before a name tells TKB to treat the name as an object 
module and to search your UFD for a file with that name and a type of 
OBJ. That is, the colon tells TKB to process what follows as an 
argument of /LB, and the comma tells TKB to treat what follows as a 
file name. 


This method of specifying an object library search is more direct and 
faster than the method described in Section 6.2.3. If you are using a 
large library, TKB need search only the module name table for those 
object modules you specify. The disadvantage is that the 
responsibility is yours to specify the names of all the modules’ that 
your task requires. In one situation, this is the only method to use 
a library. If you are using a library with zero entry points, this is 
the sole method of telling TKB which modules to include from that 
library. 
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6.2.3 Using the Library to Resolve Undefined Global Symbols 


Often the modules in a task refer to global symbols that are defined 
in other modules. If the modules that define the global symbols 
reside in a library, you can have TKB search the library. In DCL, the 
/LIBRARY qualifier on an input file specification for a LINK command 
indicates that the entire library is to be searched. The /LIBRARY 
qualifier replaces the /INCLUDE qualifier. The following example 
shows the form of the command line: 


DCL>LINK/TASK:LB/MAP:LB FILE, USROBJ/LIBRARY 
> 


The /LIBRARY qualifier tells TKB to search the library entry point 
table for symbols that are referred to but not defined. When TKB 
finds a symbol in the table that is unresolved in the task, it 
extracts the defining module and places it in the task. If any 
symbols remain unresolved after the user library search, TKB searches 
the system library. 


This method requires less effort on your part than using the /INCLUDE 
qualifier, but if you are using a large library, the task build may 
take considerable time. 


The following command line is the MCR equivalent for using the TKB /LB 
switch to search an entire library: 


MCR>TKB LB,LB/-SP=FILE,USROBJ/LB 
> 


The designation /LB with no module names tells TKB to search the 
library entry point table for symbols that are referred to but not 
defined. When TKB finds a symbol in the table that is unresolved in 
the task, it extracts the defining module and places it in the task. 
If any symbols remain unresolved after the user library search, TKB 
searches the system library. 


This method of specifying an object library search requires less 
effort on your part than the method described in Section 6.2.2, 
because TKB searches the entry point table to resolve any global 
references undefined at that point in the processing. If you are 
using a large library, TKB may take longer in searching the entry 
point table than if you had specified the names of the modules to 
include in your task. 


In certain circumstances, you may want TKB to definitely include 
specific modules from the library and also to search the same library 
to resolve any undefined references that may occur. For example, you 
may have conditional code in the main part of a task and do not know 
what global symbols are referenced. TKB allows you to specify the two 
forms of the library search. In DCL, this can be done by combining 
the /INCLUDE qualifier and /LIBRARY qualifiers in the same command 
line: 


DCL>LINK/TASK: LBOPT/MAP: LBOPT 
File(s)? FILE, USROBJ/INCLUDE:TTREAD, USROBJ/LIBRARY 
> 
or 
DCL>LINK/TASK: LBOPT/MAP: LBOPT FILE, USROBJ/INC:TTREAD, USROBJ/LIB 
> 
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Once again, the arguments to /TASK and /MAP qualifiers change the 
names of the associated output files. The /INCLUDE qualifier on the 
file specification for USROBJ.OLB instructs TKB to extract the named 
module. Notice that since only one module is named, the parentheses 
are unnecessary. The /LIBRARY qualifier on the file specification for 
USROBJ.OLB tells TKB to search that library for any unresoived globai 
symbols. TKB includes in the task any modules from the library that 
are unreSolved at that point in the building of the task. If any 
unresolved symbols remain after the search of the user library, MTKB 
searches the system library. 


The following command line shows the MCR procedure for specifying two 
forms of library search to TKB: 


MCR>TKB LBOPT, LBOPT/-SP=FILE, USROBJ/LB: TTREAD, USROBJ/LB 
> 


The first appearance of the /LB designation tells TKB to extract the 
named module. The second occurrence tells TKB to search the library 
for any unresolved global symbols. TKB includes in the task any 
modules from the library that define the global symbols that are 
unresolved at that point in the building of the task. If any 
unresolved symbols remain after the user library search, TKB searches 
the system library. , 


6.3 MAINTAINING USER LIBRARIES 


This section decribes three simple operations to maintain a _ user 
library: adding modules to, replacing a module in, and obtaining 
information about the library. MCR users accomplish these ends with 
various commands to LBR. From DCL, use the LIBRARY/INSERT, 
LIBRARY/REPLACE, and LIBRARY/LIST commands. 


6.3.1 Adding Modules to a Library 


Modules can be added to a library with the LIBRARY/INSERT command. 
Here is an example: 


DCL>LIBRARY/INSERT 
Library? USRMAC.MLB 
Module(s)? MAC1,MAC2 
> 


or 


DCL>LIBRARY/INSERT USRMAC.MLB MAC1,MAC2 
> 


Give the name and type of the library in response to the Library? 
prompt. Give the names of the files containing the library modules in 
response to the Module(s)? prompt. The default file type for files 
containing library modules is the same as for the type of library that 
you specify. 


You cannot add modules to a library that has no remaining entries in 
the module name table. (If you are créating an object module library, 
there must be sufficient entry point table slots as well.) When LBR 
inserts a module in a library, it checks to be sure that a module of 
the same name does not currently reside in the library. If such a 
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module is found, LBR reports an error and exits. (For inserting 
object modules, LBR also checks for duplicate entry point names.) To 
add modules with duplication, see the discussion of LIBRARY/REPLACE in 
Section 6.3.2. 


From an MCR terminal, modules can be added to a library with an LBR 
command line such as the following: ; 


MCR>LBR USRMAC.MLB/IN=MAC1 ,MAC2 
> 


To add modules to a library, specify the name and type of the library 
file and the /IN designation (insert) to the left of the equal sign in 
the LBR command line. To the right of the equal sign, give the name 
of the modules, separated by a comma. You need not supply a file type 
because LBR applies the correct type as a default according to the 
type of the library you specify. 


The library must have a sufficient number of name table entries 
available (and, for object modules, entry point table slots). Each 
global symbol in an object module requires an available entry point 
table slot. A module name table entry must be available for each 
object module and macro definition added. When inserting a module, 
LBR checks to ensure that a module of the same name does not currently 
reside in the library. If a duplicate name is found, the program 
reports the duplicate name and terminates. For object modules being 
inserted, LBR also checks for duplicate entry point names. To add 
modules with duplication, you must either eliminate the duplicate 
names or change the /IN designation to /RP (replace). See Section 
6.3.2. 


6.3.2 Replacing a Module in a Library 


After you create a library, a typical maintenance function you will 
perform is changing and updating modules in the library. Because a 
module of the same name (and, for object modules, the same entry 
points) already exists, you must perform a replace operation 


aS r BvsavVuie 


In DCL, this is done with the LIBRARY/REPLACE command: 


DCL>LIBRARY/REPLACE 
Library? USROBJ 
Module(s)? FILEA 
Module "TTREAD" replaced 


? 
or 


DCL>LIBRARY/REPLACE USROBJ FILEA 
Module "TTREAD" replaced 


> 


This command line causes LBR to logically delete the module TTREAD and 
all associated entry points for that name from USROBJ.OLB. LBR then 
inserts the new version of module TTREAD from FILEA.OBJ and prints a 
message. If a module to be replaced is not found in the library, LBR 
performs an insertion but prints no message. 


Note that LIBRARY/REPLACE causes a logical deletion and does not 
reclaim the space occupied by the module you replace. To reclaim this 
lost space, you should occasionally use the LIBRARY/COMPRESS command. 
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The following command line is the MCR equivalent for performing the 
replace operation: 


MCR>LBR USROBJ/RP=FILEA 
Module “TTREAD" replaced 


> 


LBR accesses the library file USROBJ.OLB, logically deletes the module 
TTREAD and all of the entry points for that name, and inserts the new 
version of module TTREAD from the file FILEA.OBJ. LBR prints a 
message telling you the name of each module it replaced. If a module 
to be replaced does not exist in the library file, LBR assumes that 
the module is to be inserted, automatically inserts it, but does not 
print the message. 


LBR does not automatically reclaim the space occupied by a module that 
you replaced. Therefore, to reclaim this lost space, you should 
occaSionally run LBR and compress the library file. 


6.3.3 Obtaining Information about a Library 


To obtain information about a library from a DCL terminal, type a 
LIBRARY/LIST command in the following format: 


DCL>LIBRARY/LIST: LBLIST/NAMES/ FULL 
Library? DD.OLB 
> 


or 


DCL>LIB/LIS: LBLIST/NAMES/FULL DD.OLB 
> : 


This command line causes LBR to access the library file DD.OLB. The 
list appears in the file in your UFD called LBLIST.LST. The qualifier 
“FULL lists entry points and full information (size, date of creation, 
and for object modules, identification). 


To list the information on the terminal instead of a file, use the 
LIBRARY/LIST command without a file specification argument to the 
/LIST qualifier: 


DCL>LIBRARY/LIST/FULL USRMAC.MLB 


(LBR lists information) 
> 


To obtain information about a library from an MCR terminal, type a 
command line to LBR similar to the following: 


MCR>LBR DD.OLB, LBLIST/LE/FU/-SP 
> 


This command line causes LBR to access the library file DD.OLB in the 
default UFD. The comma separates the library file name from the 
listing file specification. The designations /LE and /FU tell LBR_ to 
list entry points and full information (size, date of creation, and, 
for object modules, identification) in the file LBLIST.LST in the 
default UFD. The designation /-SP inhibits automatic spooling of the 
listing to the line printer. 
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To list information at the terminal, simply omit the file name from 
the command line, as follows: 
MCR>LBR USRMAC.MLB/FU 
(LBR lists information) 
> 


Because a macro library does not have entry points, you can omit the 
/LE designation from the command line. 


MCR>LBR [1,1] USROBJ.OLB, [303,10] LBLIST/LE/FU 
> 


This command line causes LBR to access the library file USROBJ.OLB in 
UFD [1,1]. The comma separates the library file name from the listing 
file specification. The designations /LE and /FU tell LBR to list 
entry points and full information (size, date of creation, and, for 
object modules, identification) in the file LBLIST.LST in UFD 
[303,10]. If you omit the UFD specification from the listing file, 
LBR creates the listing file in the UFD of the library. 


To list information at the terminal, simply omit the file name from 
the command line, as follows: 


MCR>LBR [1,1]USRMAC.MLB/FU 
> 


Because a macro library does not have entry points, you can omit the 
/LE designation from the command line. 


6.4 GUIDE TO FURTHER READING 


The sections or chapters in the following documents contain additional 
information on the subjects described in this chapter. 


Document 
RSX-11M/M-PLUS Command Language Manual 
Section 6.3, The LIBRARY Command 
RSX-11M/M-PLUS Task Builder Manual 
SéCtivin 10.1.16, /LB (Libiacy File Switch) 


PDP-11 MACRO-11 Language Reference Manual 


Section 7.8, Macro Library Directive: .MCALL 
Section 8.1.2, MCR Command String Format 

Section 8.1.2.1, MCR File Specification Switches 
Section 8.1.3, DCL Operating Procedures 


RSX-11M/M-PLUS Utilities Manual 


Chapter 10, Librarian Utility Program (LBR) 
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FORTRAN IV PROCEDURES 


PDP-11 FORTRAN IV is one of several high-level languages optionally 
available on RSX-11M and RSX-11M-PLUS systems. This chapter briefly 
introduces the product and summarizes its program development 
procedures. 


7.1 OVERVIEW OF PDP-11 FORTRAN IV 


The FORTRAN IV language processor on RSX-11M and RSX-11M-PLUS consists 
of the following elements: 


e The compiler task FOR 

e The DCL FORTRAN command 

e The MCR FOR command 

e An Object Time System (OTS) library 
@® An optional resident library 


The FORTRAN IV compiler accepts an ASCII disk file containing source 
statements, and generates a disk file in object module format and, 
optionally, a listing file suitable for printing. The user interface 
to the compiler is similar to that of the MACRO-11 Assembler. The 
program development procedures are like those for assembly language 
modules: You supply the object file to the Task Builder (TKB) to 
obtain an executable program. 


The DCL FORTRAN command parallels in function the DCL MACRO command, 
and the MCR FOR command parallels in function the MCR MAC command. 
The FORTRAN and FOR commands pass an ASCII source file to the FORTRAN 
compiler, and the compiler generates an object module and, if desired, 
a listing file. The program development procedures are very similar 
to those for assembly language modules: You pass the object module to 
TKB using a LINK command to obtain a file containing an executable 
task image. 


The FORTRAN IV Object Time System (OTS) is a collection of object 
module subroutines the system uses as needed in creating an executable 
program. On systems with more than one high-level language, the OTS 
routines for FORTRAN IV must be segregated from those of other 
languages. Sometimes, the OTS routines reside in the system object 
library SYSLIB. Regardless of their location, however, the OTS 
routines must be accessible to the Task Builder. The difference to 
you is whether the library containing the OTS routines must be 
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explicitly named. If the OTS routines are in SYSLIB, the Task Builder 
can locate them without an explicit specification because, as a 
default condition, it automatically searches the System library. 


The FORTRAN IV compiler does not generate all of the machine code 
required by a task at run time. Common sequences of code reside in 
the OTS library. During compilation, FORTRAN IV flags these common 
Sequences as undefined global symbols. The Task Builder must then 
resolve the undefined references by selecting from the OTS those 
modules that resolve the symbols in the object module. 


In a narrow sense, the OTS contains the routines that the compiler has 
previously designated to be linked into your task. In practice, 
however, the OTS can contain various routines, callable by the user, 
in addition to the routines required by the compiler-assigned 
references, 


As an option, a system installation can have a common area containing 
Shareable FORTRAN IV OTS routines. This common area, called a 
resident library, contains the most frequently used routines, taken 
from the OTS and made available for user tasks to link to and share at 
run time. Thus, with a resident library, the Task Builder generates 
references to the routines in the resident library that you specify 
when you build the task. The Task Builder does not include those 
routines in your task image. The routines use virtual address space 
in the task but do not require additional physical memory in the task 
image. The resident library, tailored to the needs and requirements 
of a particular system, saves task-build time and memory by the amount 
of code that need not be repeated in each memory-resident FORTRAN IV 
task. 


7.2 FORTRAN IV PROGRAM DEVELOPMENT PROCEDURES 


The program development procedures for FORTRAN IV are quite similar to 
those for MACRO-11. Therefore, this chapter does not include the 
level of detail found in previous chapters of this manual. To edit a 
FORTRAN IV source file, use the same commands you used to edit the 
MACRO-11 files shown in Chapter 2. If you are using an editor other 
than EDI, perform the same operations using your editor. 


7.2.1 Creating the Source File 


To create a sample FORTRAN IV source file, invoke the editor task EDI 
£n7 : 


and bha 


wan ait 
re POTOr wet aren s 


lowing Commands Lo insert the lines of code shown in 
Example 7-1. 


MCR>EDI AVERAGE. FTN 
{CREATING NEW FILE] 


INPUT 
insert the lines here and 
type the RETURN key twice to exit from 
insert mode 

GED) 

RED 

*EXIT 

{EXIT] 

> 
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Because EDI cannot insert a blank line in the text (EDI requires at 
least one nonprinting character such as a space or tab character; see 
Section 2.2.1.1), be sure to use the C (comment line) in column 1 of 
the source file in place of the blank line, for readability. If you 
insert a line with a space or tab character in it, the FORTRAN IV 
compiler generates an error because it expects a valid label on a 
nonblank line. 


You can use the TAB character to facilitate line formatting. The 
FORTRAN IV compiler positions the character following an initial TAB 
character to the proper column. That is, a digit following an initial 
TAB is considered a continuation character (column 6), and a nondigit 
is considered the beginning of the statement (column 7). 


Example 7-1 FORTRAN IV Sample Source Code AVERAGE.FTN 


PROGRAM AVERAGE 


c PROGRAM TO COMPUTE AVERAGE OF NUMBERS ENTERED AT TERMINAL 
c THE NUMBER ‘0’ INDICATES END OF INPUT 
c 
TOTAL = 0 ! INITIALIZE ACCUMULATOR 
N= 0 1 INITIALIZE COUNTER 
5 N=N#41 
WRITE (5210) ! PROMPT TO ENTER NUMBER 
16 FORMAT (’ ENTER NUMBER> END WITH 0/7) 
READ (5220) K ! READ NUMBER FROM TERMINAL 
29 FORMAT I10 
IF (K -EQ. 0) GOTO 40 ! 0 MEANS NO MORE INPUT 
TOTAL = TOTAL + K ! COMPUTE TOTAL WITH NUMBER 
GO 70 5 
C 


C NOW, COMPUTE TOTAL BY DIVIDING IT BY THE NUMBER OF TIMES 
C THROUGH THE LOOP 


c 
40 TOTAL = TOTAL/N 

WRITE (5:50) TOTAL ! DISPLAY THE RESULT 
50 FORMAT (° AVERAGE IS ‘sF10.2) 

STOF 

END 


7.2.2 Performing a Diagnostic Run 


To determine whether there are any syntax or grammar errors in a 
source file, you can perform a diagnostic run using the DCL FORTRAN 
command line, as follows: 


DCL>FORTRAN/NOOBJECT AVERAGE/LIST 
AVERAG 

FOR -- [AVERAG] ERRORS: 1, WARNINGS: 0 
. ; 


This command line requests FORTRAN IV to compile the file AVERAGE.FTN 
and create a listing file, AVERAGE.LST, but no object file. By 
default, the listing file contains source code and diagnostic messages 
only. 
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When you request a listing file in a compilation, FORTRAN IV reports 
at the terminal the ame of the program unit being compiled and a 
summary of any errors. To discover what caused any errors, you must 
examine the section of the listing entitled FORTRAN IV DIAGNOSTICS. 
List the file on your terminal with the DCL TYPE command, as shown: 


DCL>TYPE AVERAGE.LST 


(PIP displays listing) 


See the following discussion of the MCR format for information on 
reading the listing file. 


To perform the diagnostic run from an MCR terminal, issue the 
following command line: 


MCR>FOR ,AVERAGE/-SP=AVERAGE 

AVERAG 

FOR -- [AVERAG] ERRORS: 1, WARNINGS: 0 
> 


This command line requests FORTRAN IV to compile the file AVERAGE.FTN, 
which resides in your’ UFD. The compiler creates a listing file, 
AVERAGE.LST, but no object module. (The leading comma in the command 
means a null file specification for the object file. If you omit the 
comma, FORTRAN IV creates the object file but not the listing file.} 
As a default condition, the listing file contains source code and 
diagnostic messages only. 


When you request a listing file in a compilation, FORTRAN IV reports 
at the terminal the name of the program unit being compiled and a 
summary of errors found. To discover what caused any errors, you must 
examine the section of the listing entitled FORTRAN IV DIAGNOSTICS. 
Display the listing file by typing the following MCR command line: 


MCR>PIP TI:=AVERAGE.LST 
(PIP displays listing) 
> 


On a video display terminal, use the CTRL/S and CTRL/Q commands. to 
stop and resume output. 


The following line appears in the diagnostic section of the listing: 
IN LINE 0008, ERROR: SYNTAX ERROR 


Line 0008 refers to the statement number 0008 assigned by the 
compiler. The error referred to is described in an appendix of the 
language user's guide. In the source code part of the listing, line 
0008 is shown as follows: 


0008 20 FORMAT 110 


The compiler detected missing parentheses on the field descriptor in 
the FORMAT statement. To correct the error, you must edit the source 
file, as in the following example: 


MCR>EDI AVERAGE.FITN 
[00023 LINES READ IN] 
[PAGE 1] 

*L I10 GED 

20 FORMAT 110 
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*C /110/(110)/ 

20 FORMAT (110) 
* EXIT GED 

[EXIT] 


> 


The L command locates the line containing the string 110 and prints 
the entire line. The C command replaces the string I10 with (I10) and 
prints the line so that you can verify the change. The EXIT command 
terminates the editing session and creates the new, edited version of 
the file. Next, you can use the edited version to create an object 
module. 


7.2.3 Creating an Object Module 


To create an object module, simply omit the /NOOBJECT qualifier from 
the DCL command line you entered previously: 


DCL>FORTRAN AVERAGE/LIST 
AVERAG 
> 


This command line requests FORTRAN IV to compile file AVERAGE.FTN, and 
to create listing file AVERAGE.LST and object file AVERAGE.OBJ. If 
FORTRAN IV detects any errors, it prints a summary at the terminal 
(see Section 7.2.1). If there are no errors, FORTRAN IV returns 
control to DCL, which prints the > prompt. 


Here is the same procedure from an MCR terminal: 


MCR>FOR AVERAGE, AVERAGE/-—SP=AVERAGE 
AVERAG 
> 


This command line requests FORTRAN IV to compile file AVERAGE.FTN, and 
to create object file AVERAGE.OBJ and listing file AVERAGE.LST. If 
FORTRAN IV detects any errors, it prints a summary at the terminal as 
described in Section 7.2.1. If there are no errors, FORTRAN IV 
returns control to MCR, which prints the > prompt. 


7.2.4 Creating a Task Image 


FORTRAN IV object modules do not contain all the object code required 
at run time. Therefore, when you run the Task Builder, either from 
MCR or with the DCL LINK command, you must specify as input both the 
name of the object module and the name of the library containing the 
FORTRAN IV OTS routines. The commands for both DCL and MCR users 
follow: 


DCL>LINK AVERAGE, LB: [1,1] FOROTS/LIBRARY 
or 


MCR>TKB AVERAGE=AVERAGE, LB: [1,1] FOROTS/LB 
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These command lines request the Task Builder to resolve any undefined 
references by searching the library FOROTS.OLB in UFD [1,1] on the 
system library device, and linking compiler-designated routines to 
Module AVERAGE.OBJ.1 You can add, as input to the Task Builder, file 
names of any external object modules that the main module calls. As a 
result of the command line, the Task Builder creates a task image file 
AVERAGE.TSK. (A memory allocation file is not needed.) If the Task 
Builder detects any errors, it proceeds according to whether the error 
is fatal or diagnostic. Refer to an appendix in the RSX-11M/M-PLUS 
Task Builder Manual for guidelines'on error processing. 


NOTE 


When building a task image, the library 
FOROTS.OLB may contain routines’ that 
support the FP-11 floating point 
processor. .-If this is the case, the 
commands for DCL and MCR users are as 
follows: 


DCL> LINK/CODE : FPP AVERAGE, LB: [1,1] FOROTS/LIBRARY 
MCR>TKB AVERAGE/FP=AVERAGE, LB: [1,1] FOROTS/LB 


You also must use these commands when 
you rebuild your task after debugging 


it 


The task image created by the Task Builder has certain default 
conditions. The task AVERAGE can be built to run successfully without 
having to override these default conditions. When you build a_ task 
from a FORTRAN IV module, you may have to specify special switches in 
the command line or supply options to the Task Builder. Refer tc the 
language user's guide for information regarding Task Builder default 
FORTRAN IV conditions and FORTRAN-specific options and switches. See 
also the description of the FORTRAN command in of the RSX-11M/M-PLUS 
Command Language Manual. 


7.2.5 Running and Debugging a Task 


To execute the task AVERAGE, type the following DCL or MCR _ command 
line: 


>RUN AVEKAGE 


1. In the command line, the name shown for the FORTRAN IV Object Time 
System (FOROTS) is only a convention recommended by DIGITAL. Consult 
the system manager at your installation because the FORTRAN IV OTS 
routines may reside in another library or in the system library 
SYSLIB. (If the OTS routines do reside in SYSLIB, you need not 
specify the name of the OTS in the command line to the Task Builder 
because the Task Builder automatically searches the system library.) 
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The program will then display the following lines on your terminal: 


ENTER NUMBER, END WITH 0 
euiee NUMBER, END WITH 0 
een NUMBER, END WITH 0 
UENCE Is 44.00 
in -- STOP 


Obviously 44 is not the average of 66 and 66; therefore, there must 
be an error in the program. If you cannot locate the error by looking 


at the program listing, you can attempt to locate the error by placing 
debugging statements in the code. 


To add debugging statements to the program, simply edit the source 
file with lines of code beginning with D in column 1. For example, 
you can include statements to print values of variables before and 
after the loop, as follows: 


MCR>EDI AVERAG. FTN 
[00023 LINES READ IN] 
[ PAGE 1] 


*L 5 GED 

5N=NH1 

* T GED 

D&® WRITE (5,6) N, TOTAL 

D6 (8) FORMAT (' ***DEBUG LINE N = ',110,', TOTAL = ',F10.0) @e 
GED 


*L 508) (RED 

50 FORMAT (' AVERAGE IS ',F10.2) 

*T RED 

D A) WRITE (5,51) N 

D51 (AB FORMAT (' ***DEBUG LINE N 
ED) 

* EXIT GED 

{EXIT] 


*,110) & 


> 


The L commands locate and print the contents of the lines that precede 
where debugging statements are to be placed. The I commands insert 
the debugging statements. You terminate the insert operation by 
typing two successive RETURN keys. After the inserts are made, the 
EXIT command closes the file and terminates EDI. 


Next, recompile the module and request FORTRAN IV to include the 


debugging statements, as shown in the following DCL and MCR command 
lines: 


DCL> FORTRAN/OBJECT:DEBUG/D_LINES/LIST: DEBUG 
File(s)? AVERAGE 

AVERAG 

> 


or 
MCR>FOR DEBUG, DEBUG=AVERAGE/DE 


The compiler generates the files DEBUG.OBJ and DEBUG.LST. Because of 
the /D_LINES qualifier (/DE designation in the MCR line), the compiler 
includes statements beginning with D in column 1. If you omit this 


qualification, the debugging lines are treated simply as comment 
lines. 


FORTRAN IV PROCEDURES 
Now, rebuild the task with debugging lines, using the DCL or MCR 
command lines as shown: 


DCL>LINK DEBUG, LB: [1,1] FOROTS/LIBRARY 
> 


or 


MCR>TKB DEBUG=DEBUG, LB: [1,1] FOROTS/LB 
> 


Note that this operation has nothing to do with ODT, which is a 
MACRO-11 debugging tool. 


Run the task with the following DCL or MCR command line: 


>RUN DEBUG 

***DEBUG LINE N = 1, TOTAL = 0. 
ENTER NUMBER, END WITH 0 

66 

***DEBUG LINE N = 2, TOTAL = 66. 
ENTER NUMBER, END WITH 0 

66 

***DEBUG LINE N = 3. TOTAL = 132. 
ENTER NUMBER, END WITH 0 

0 

AVERAGE IS 44.00 

***xDERUG LINE N = 3 

TT30 -- STOP 

> 


The debugging statements enable you to inspect the values of 
variables. As you can see, the loop counter N is incremented one 
extra time for the number 0. The value N must be decremented by l. 


To correct the error, edit the source file as follows: 


MCR>EDI AVERAGE. FTN 
[00027 LINES READ IN] 
[PAGE 1] 

+L TOTAL/ § 

40 TOTAL = TOTAL/N 

*C 3N;(N-1); 

40 TOTAL = TOTAL/(N-1) 
*EXIT GD 

[EXIT] 

> 


Next, repeat the compile, link, and run operations. From a DCL 
terminal, use the following sequence of command lines: 


DCL> FORTRAN AVERAGE/LIST 
AVERAG 

>LINK AVERAGE, LB: [1,1] FOROTS/LIBRARY 
>RUN AVERAGE 

ENTER NUMBER, END WITH 0 
66 

ENTER NUMBER, END WITH 0 
66 

ENTER NUMBER, END WITH 0 
0 

AVERAGE IS 66.00 

TT30 -- STOP 

> 
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The program is compiled without the debugging statements. 
shows that the correction eliminated the error. 


Here is the same procedure from an MCR terminal: 


MCR>FOR AVERAGE , AVERAGE/-SP=AVERAGE 
AVERAG 

>TKB AVERAGE=AVERAGE, LB: [1,1] FOROTS/LB 
>RUN AVERAGE 

ENTER NUMBER, END WITH 0 

66 

ENTER NUMBER, END WITH 0 

66 

ENTER NUMBER, END WITH 0 

0 

AVERAGE IS 66.00 

TT30 -- STOP 

> 


The program is compiled without the debugging statements. 
shows that the correction eliminated the error. 


7.3 GUIDE TO FURTHER READING 


The section or chapters in the following documents contain 
information on the subjects described in this chapter. 


Document 


The output 
The output 
additional 


Section 1.3, Using the Task Builder to Link FORTRAN IV Programs 


Section 1.6, Debugging a FORTRAN IV Program 

Section 2.1, FORTRAN IV Object Time System 

Section 2.2, Object Code 

Section 2.9, OTS and Shareable Libraries 

Appendix C, FORTRAN IV Error Diagnostics 
RSX-11M/M-PLUS Command Language Manual 

Section 6.2.3, FORTRAN Command 
RSX-11M/M-PLUS Task Builder Manual 


Appendix H, Error Messages 
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Data storage, 
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MACRO-11 source file, 
3-3 to 3-4 
task, 4-9, 5-1 to 5-2, 
7-7 to 7-9 
tool, 
See ODT 
using map, 
DEC Standard 
See EDT 
Default, 
file type, 
MACRO-11, 
TKB, 4-1 
system library search, 
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altering, 
text, 2-16, 7-5 
AP command, 2-17 
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END command (EDI), 2-14 
-END directive, 2-7, 3-4, 4-3, 
4-8 
Entry point, 6-5 to 6-6 
table, 6-5, 6-9 to 6-10 


zero entry points, 6-7 
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MACRO-11, 
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TKB, 4-2 
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2-12, 2-18, 7-5, 7-7 
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source, 2-9 to 2-10 
directory listing, 3-9 
editing, 
source, 2-9, 2-12 to 2-18 
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printing, 3-8 to 3-9 
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File type, 
~FTN, 7-3 to 7-4 
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2-21 to 2-22 
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2-23 to 2-24 
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FOR compiler task, 7-1 
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/DE,; 7-7 
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diagnostic run, 7-3 to 7-4 
/D_LINES, 7-7 
FOR command (MCR), 7-1, 7-4 
FORTRAN command (DCL), 7-1, 
7-3 
-FTN file type, 7-3 to 7-4 
/LIST, 7-3, 7-7 
/NOOBJECT, 7-3 
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statement, 
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source file, 
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1-11 
FORTRAN command (DCL), 
7-3 
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7-1, 
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FORTRAN IV (Cont.) 
source file, 
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comment file, 7-3 
specifying OTS to TKB, 7-5 
FORTRAN IV-PLUS, 
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FTB (Fast Task Builder), 4-4 
.FTN file type, 7-3 to 7-4 
See also FOR compiler task 


G command (ODT), 5-6, 5-8 
Global cross-reference, 
listing, 4-5 to 4-6 
Global default, 
disabling in MACRO-11, 
3-1 to 3-2 
Global symbol, 1-4 to 1-5 
entry point, 1-4, 

6-5 to 6-6, 6-10 
resolution, 4-2, 6-8 to 6-9 
using library to resolve 

undefined, 6-8 to 6-9 


Hardware, 
program development, 1-12 


~ IDENT directive, 2-5 
INSERT command (EDI), 
7-7 
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characters in a line, 2-17 
code in the source file, 
2-18 
lines in a file, 2-9, 
modules in a library, 
6-9 to 6-10 


2-18, 


2-18 
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assembly, 1-4 to 1-5 
See also MACRO-11 
LBR command (MCR), 1-9, 
See also LBR 
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adding a module to a 
library, 6-9 to 6-10 
/COMPRESS, 6-10 
/CR, 6-2, 6-5 
/CREATE, 6-1, 6-4 to 6-5 
efficiency, 1-9 
/FU, 6-11 to 6-12 
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LBR (Librarian Utility Line Text Editor, 
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/FULL, 6-11 LINK command (DCL), 1-5, 4-1, 
/IN, 6-10 5-1, 5-9, 6-7 
/INSERT, 6-9 See also TKB 
LBR command (MCR), 1-9, 6-2 LIST command (EDI), 2-13 
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6-1 assembly, 3-4 to 3-5 
/LIST, 6-9, 6-11 control, 1-4 to 1-5, 2-6 
listing information, directory, 3-9 

6-11 to 6-12 examining at a terminal, 
/MACRO, 6-1 to 6-2 3-6, 7-4 
Macro library, 6-1 to 6-3 FORTRAN IV, 7-5 
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-OLB file type, 6-4 use in debugging, 5-4 
/REPLACE, 6-9 to 6-10 Local data block, 2-8 
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/RP, 6-10 to 6-11 Local symbol, 1-4 to 1-5 
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Librarian Utility Program, LOCATE command (EDI), 2-14, 
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See also Macro, Object, OTS use in debugging, 5-3 to 5-4 
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TKB, 4-2 See LUN 
DIGITAL-supplied, 1-9 -LST file type, 3-4, 6-11, 
macro, 6-1 to 6-3 7-3 to 7-4 
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system, 1-11 MAC command (MCR), 1-4, 3-l, 
using to resolve undefined 3-5, 6-3 
global symbols, See also MACRO~11 
6-8 to 6-9 -MAC file type, 3-1 
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a user, 6-11 to 6-12 See MACRO-11 
OTS, 7-2 Macro, 
search, call, 

MACRO-11, 1-5, 1-10, 2-7 cross-reference of 
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squeezing, 6-3 resolution, 1-4, 1-10, 2-7 
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macro (RSXMAC.SML), 1-5 library, 6-1 to 6-3 
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6-1 6-9 to 6-10 
See also LBR creating a user, 
LINE FEED key, 6-1 to 6-3 
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5-7 ‘ DIGITAL-supplied, 1-9 
displaying word on stack listing information, 

(ODT), 5-8 _ 6-11 to 6-12 
opening location (ODT), 5-5, replacing modules, 
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Macro (Cont.) MACRO~-11 (Cont.) 
search of system, 1-5, symbol, 
1-10, 2-7 cross-reference, 
symbol, 3-7 to 3-8 
definition, 1-4, 1-10, evaluation, 1-4, 
2-7, 6-4 3-1 to 3-2, 6-4 
MACRO command (DCL), 1-4, 3-1, table of contents 
3-4, 6-3 generation, 2-6 
See also MACRO-11 - Map, : 
MACRO-11, 1-5 debugging use, 5-2, 5-8 
assembling source file, examining at terminal, 4-6 
3-1 to 3-2 full, 4-7 
/CR, 1-8, 3-8 generating, 4-5 to 4-7 
/CROSS REFERENCE, 1-8, 3-7 reducing width, 4-5 to 4-6 
cross-reference listing, stack limits, 5-8 
i-5, 1-7, 3-7 to 3-8 standard, 4-5 to 4-6 
data storage, -MAP file type, 4-6 
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default search of system 2-6 to 2-7, 3-3 
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2-7 library, 6-3 to 6-4 
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2-7 to 2-8 1-1 to 1-3 
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/LIST, 3-1, 3-4 to 3-5, 3-7 

listing, 3-4 to 3-5 »NLIST BEX directive, 2-6 
generation, 3-6 
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MAC command (MCR), 1-4, 3-1, 
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3-7 to 3-8 adding modules, 

library usage, 6-3 to 6-4 6-9 to 6-10 
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MACRO command (DCL), 1-4; 6-4 to 6-6 

3-1, 3-4, 6-3 default search of system, 

/ML, 6-3 to 6-4 1-11, 4-2 
/NOOBJECT, 3-1 DIGITAL-supplied, 
/OBJECT, 3-4 1-10 to 1-11 
object module, 3-4 to 3-6 dual use, 6-8 to 6-9 
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format, 2-1 to 2-3 6-11 to 6-12 

skeleton, 2-4 OTS, 7-1 to 7-2 
source input, 1-4 using to resolve undefined 
/-SP, 3-5, 3-8 global symbols, 
statement format, 2-3 6-8 to 6-9 
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Object (Cont.) 
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FORTRAN IV, 7-5 to 7-6 
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MACRO-11, 1-4, 3-4 to 3-6 
Object Time System, 
See OTS 
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1-6 to 1-7 
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backslash character (\), 5-5 
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changing location contents, 
5-7 
correcting input, 5-3 
dollar sign (S$), 5-6 to 5-8 
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5-4 to 5-5 
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5-1 to 5-2 
LINE FEED key, 5-5, 
5-7 to 5-8 
map use, 5-2 
ODT.OBJ file, 5-1 
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R command, 5-3 
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5-2 to 5-4 
RETURN key, 5-8 
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setting up a task with, 1-7 
Slash character ,(/), 5-4 
source listing use, 5-4 
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terminating task execution, 
5-8 
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X command, 5-8 ~ 
OLB file type, 6-4 
See also LBR 
On-Line Debugging Tool, 
See ODT 
OTS (Object Time System), 
library, 7-1 to 7-2 
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-PAGE directive, 2-6 

PC (Program counter), 
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Peripheral Interchange 
Program, 
See PIP 
PIP (Peripheral Interchange 
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3-9 to 3-10 
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object module, 
4-3 to 4-4 
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/LI, 3-9 
/ME, 4-3 to 4-4 
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/SP, 3-8 
spooling listing, 3-8 to 3-9 
PLOCATE command (EDI), 2-15 
-PMD file type, 5-10 
See also PMD 
PMD (Postmortem Dump), 1-7 
enabling with TKB, 5-9 
Postmortem Dump, 
See PMD 
PRINT command (DCL), 1-12, 3-8 
PRINT command (MCR), 3-9 
Printer, 1-12 
Program, 
sectioning, 1-4 to 1-5, 2-5, 
_ 2-8 to 2-9 
user, 
breakpoints, 
setting, 5-6 
FORTRAN IV, 7-3 
library, 6-1 
macro symbol, 6-4 
definition placement, 
1-5 
module, 
name, 2-3, 2-5 
version, 2-5 
object library routines, 
6-6 
overview of development, 
1-13 to 1-14 
section definiton, 
2-8 to 2-9 
system routines, 1-11 
Program counter, 
See PC 
Programming, 
advanced, 
techniques, 1-6 
»PSECT directive, 2-8 to 2-9 
PURGE command (DCL), 3-9 
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OMG {Queue Manager), 1-12 
Question mark (?), 

ODT, 5-3 
Queue Manager, 

See OMG 


Record Management Services, 
See RMS-11l 
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breakpoint, 5-6 
relocation, 5-2 to 5-4 
Relocation register, 
5-2 to 5-4 
RENEW command (EDI), 2-15 
RETURN key, 
closing location (ODT), 5-5, 
5-8 
displaying new line (EDI), 
2-13 
entering text (EDI), 2-9 
terminating input (EDI), 
2-9 to 2-10, 2-18, 7-7 
RMS-11 (Record Management 
Services), 
library, 1-9, 1-11 
RMSLIB.OLB (Record Management 
Services library), 1-11 
RMSMAC.MLB (Record Management 
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RSXMAC.SML (System macro 
library), 1-5, 
1-9 to 1-10, 2-7 
RUN command, 4-7, 5-2, 7-6 


-SBTTL directive, 2-6 
Skeleton, 

source file (MACRO-11), 2-4 
Slash character (/), 

EDI, 2-16 

ODT, 5-4 
SSNAP (Snapshot dump), 

1-7 to 1-8, 5-9 to 5-10 
subset of Postmortem Dump 
Task, 5-9 to 5-10 

Snapshot dump, 
See SSNAP 
Source file (FORTRAN IV), 
adding debugging statements, 
7-7 
blank line, 7-3 
comment line, 7-3 
creating, 7-2 to 7-3 
7-9 
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Source file {MACRO-11), 
assembling, 3-1 to 3-2 
creating from a skeleton, 

2-12 
editing, 2-13 to 2-18 
error, 3-2 to 3-4 
format, 2-1 to 2-3 

skeleton, 2-4 

inserting lines, 2-18 
listing, 3-4 to 3-6 
macro library call, 

6-3 to 6-4 
preface, 2-1 

SST (Synchronous system trap), 
ODT, 5-8 
relation to Postmortem Dump, 

1-7 
role in task termination, 
4-8 to 4-9 
Statement, 
MACRO-11, 1-4 
format, 2-3 

Symbol, 
cross-reference, 3-7 to 3-8 
global, 1-5 

entry point, 1-4 
resolution, 1-4 to 1-5, 
4-2 
local, 1-4 to 1-5, 
2-7 to 2-8 
definition, 2-7 to 2-8 
macro, 
definition, 1-4, 1-10, 
2-7, 6-4 
MACRO-11 evaluation, 1-4, 
3-1 to 3-2 

Synchronous system trap, 
See SST 

SYSLIB.OLB (System library), 

1-11 

System, 
directive, 1-9 to 1-10 
library, 

contributions (in map), 
4-7 
macro (RSXMAC.SML), 1-5, 
1-9 to 1-10 
contents, i-9 
search, 1-5, 1-10, 2-7 
object (SYSLIB.OLB), 1-11 
contents, 1-11 
search, 1-ll, 4-2 
task, 1-1 


Task, 
abort, 4-8 
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Task (Cont.) TKB (Task Builder) (Cont.) 
breakpoints, standard, 4-5 to 4-6 
setting, 5-6 /INCLUDE, 6-7 to 6-9 
building, 4-1, 7-6 input, 1-5 to 1-6 
correcting, 4-9 /LB, 6-7 to 6-9, 7-8 
debugging, 4-9, 7-7 to 7-9 /LIBRARY, 6-8 to 6-9, 7-8 
default conditions, LINK command (DCL), 1-5, 
4-4 to 4-5, 4-7 to 4-8 4-1, 5-1, 5-9, 6-7 
macro calls, 6-3 to 6-4 /LONG, 4-7 
map, 4-5 /MA, 4-7 
full, 4-7 /MAP, 4-5, 4-7, 5-1, 5-9, 
Standard, 4-5 to 4-6 6-7 to 6-9 
object library routines, 6-6 /NOTASK, 4-5 
running, 4-7 to 4-8, 7-6 /NOWIDE, 4-5 
SST, 4-8 object library, 
system, 1-1 designation, 6-4 to 6-5 
system library use, 6-8 to 6-9 
contributions, 4-7 output, 1-6 
termination, 4-8 /PM, 5-9 
transfer (starting) address, /POSTMORTEM, 5-9 
default, 4-3, 4-8 search of system library, 
defining, 2-7 default, 1-11 
Task Builder, /-SH, 4-7 
See TKB symbol, 
Task image, 1-6, 4-1, 7-6 undefined, 4-2 
creating, 4-1 to 4-2, / SYSTEM LIBRARY DISPLAY, 4-7 
7-5 to 7-6 /TASK, 5-1, 6-7 to 6-9 
Task Termination and TKB command (MCR), 1-5, 4-1, 
Notification, 5-2, 5-9, 6-7 
See TKTN transfer (starting) address, 
Terminal, default, 4-3 
examining a listing, /-WI, 4-6 
3-6 to 3-7 TKTN (Task Termination and 
output, Notification), 
controlling, 3-7 abort message, 4-8 
types, 1-12 using with PMD, 1-7 
Text, Transfer (Starting) address, 
buffer, 1-3 defining, 2-7 
editor, 1-3 to 1-4 system treatment of default, 
See also EDI, EDT 4-3, 4-8 
-TITLE directive, 2-3, 2-5, Trap, 
6-7 See SST 
TKB command (MCR), 1-5, 4-1, -TSK file type, 4-1 
5-2, 5-9, 6-7 TYPE command (DCL), 3-6, 4-6, 
See also TKB 7-4 
TKB (Task Builder), 1-5 to 1-6 TYPE command (EDI), 
/CR, 1-8, 4-6, 5-2 2-13 to 2-14, 2-17 
/CROSS REFERENCE, 1-8, 4-5, 
5-1 


Underline character (_), ODT, 5-2 


/DA, 5-2 Utility programs, 1-8 to 1-9 


/DEBUG, 5-1 
error, 4-2, 4-8 to 4-9 


/FAST, 4-4 Virtual memory management, 
fast version, 4-4 library, 1-11 
generating, VMLIB.OLB (Virtual memory 
cross-reference listing, Management library), 1-11 
4-5 to 4-6 
map, 
full, 4-7 X command (ODT), 5-8 
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READER’S COMMENTS 
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the 


company’s discretion. If you require a written reply and are eligible to receive one under Software 
Performance Report (SPR) service, submit your comments on an SPR form. 


Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement. 


Did you find errors in this manual? If so, specify the error and the page number. 


Please indicate the type of user/reader that you most nearly represent. 


[] Assembly language programmer 
L) Higher-level language programmer 
[] Occasional programmer (experienced) 
L] User with little programming experience 
LJ Student programmer 
L] Other (please specify) 
Name — Date 
Organization 
Street 
City State CCCs Crcole 
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